DFRobotDFPlayerMini: play MP3 files from a DFPlayer Mini
The DFPlayer Mini is a small MP3 module with a microSD slot and a 3 W amplifier that drives a speaker directly. It decodes the files itself; the Arduino only sends commands over a 9600-baud serial link, and DFRobot鈥檚 DFRobotDFPlayerMini library builds those ten-byte frames and reads the replies.
Built in on Mokxi: #include <DFRobotDFPlayerMini.h> and it builds, with nothing to install. Free, and no account needed.
What DFRobotDFPlayerMini does
Most sketches use SoftwareSerial on two spare pins so the USB Serial stays free for messages. Put a 1 k惟 resistor in the Arduino TX to module RX line: the module runs at 3.3 V logic and the resistor stops buzzing and lockups that a direct 5 V line causes.
Files are found by number, not name. play(1) plays the first file the module finds, which follows the order files were copied to the card, not their names. For predictable order use folders 01, 02 and so on with files named 001.mp3, 002.mp3 and call playFolder(), or an mp3 folder with 0001.mp3 and playMp3Folder().
| Library Manager name | DFRobotDFPlayerMini |
|---|---|
| Author | DFRobot |
| Include | #include <DFRobotDFPlayerMini.h> |
| Boards | Arduino Uno, Arduino Nano, Arduino Mega 2560, Arduino Leonardo, SparkFun Pro Micro, Arduino Micro, Arduino Pro Mini 3.3 V, ESP8266 NodeMCU, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32 |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
| Parts it drives | DFPlayer Mini MP3 module |
Install it
It builds on Arduino Uno, Arduino Nano, Arduino Mega 2560, Arduino Leonardo, SparkFun Pro Micro, Arduino Micro, Arduino Pro Mini 3.3 V, ESP8266 NodeMCU, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32.
In Mokxi it is built in: #include <DFRobotDFPlayerMini.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "DFRobotDFPlayerMini" by DFRobot from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add DFRobotDFPlayerMini to lib_deps in PlatformIO. Mokxi follows the calls of release 1.0.6, so a sketch written here builds there too.
What to know in the simulator: The dfplayer part answers the frames and shows what it plays; there is no sound, since there are no recordings.
Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 Arduino Pro Mini 3.3 V 路 ESP8266 NodeMCU 路 ESP32 DevKit 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 ESP32-S3-DevKitC-1 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32
The calls you will use
In the order a sketch meets them.
DFRobotDFPlayerMini myDFPlayer
The player object; pair it with a SoftwareSerial mySoftwareSerial(10, 11) started at 9600.
myDFPlayer.begin(mySoftwareSerial)
Resets the module and waits for its reply. Returns false when it does not answer, with no card or a wiring fault.
mySoftwareSerial.begin(9600);
if (!myDFPlayer.begin(mySoftwareSerial)) {
Serial.println(F("Unable to begin"));
while (true);
}myDFPlayer.volume(20)
Sets the volume from 0 to 30.
myDFPlayer.play(1)
Plays track 1 in the order the files were copied onto the card.
myDFPlayer.playFolder(2, 5)
Plays 005.mp3 in folder 02, the reliable way to pick a specific file.
myDFPlayer.next()
Skips to the next track. previous(), pause() and start() do what they say.
myDFPlayer.available()
True when the module has sent a message, such as a track finishing; readType() and read() say what it was.
Example: Jukebox
On the Arduino Uno R3. It runs in the browser exactly as printed.
// Jukebox: a DFPlayer Mini plays the files on its microSD card one after
// another, driven with DFRobot's library over a software serial port.
//
// DFPlayer VCC -> 5 V GND -> GND
// RX <- 1 k <- pin 11 (the module's inputs are 3.3 V)
// TX -> pin 10
// BUSY -> pin 3 (low while a file plays)
//
// The module does the decoding itself: the sketch only sends it ten-byte
// commands, "play file 1", "volume 20", and hears back when a file ends. The
// card on the canvas holds four files of three seconds each; there is no sound,
// but the module shows what it is playing.
#include <SoftwareSerial.h>
#include <DFRobotDFPlayerMini.h>
const int BUSY_PIN = 3;
SoftwareSerial link(10, 11);
DFRobotDFPlayerMini player;
int track = 1;
int files = 0;
bool wasBusy = false;
void setup() {
Serial.begin(9600);
link.begin(9600);
pinMode(BUSY_PIN, INPUT);
if (!player.begin(link)) {
Serial.println("Unable to begin: check the wiring and the card");
while (true) {
}
}
player.volume(20);
files = player.readFileCounts();
Serial.print("Jukebox ready, ");
Serial.print(files);
Serial.println(" files");
player.play(track);
}
void loop() {
bool busy = digitalRead(BUSY_PIN) == LOW;
if (busy != wasBusy) {
wasBusy = busy;
Serial.println(busy ? "playing" : "quiet");
}
// The module reports the end of a file twice; only the report for the
// file that is playing moves on.
if (player.available() && player.readType() == DFPlayerPlayFinished && (int)player.read() == track) {
Serial.print("finished file ");
Serial.println(track);
track = track % files + 1;
delay(200);
player.play(track);
}
}Open it in the editor, wired and ready to run 路 Jukebox: the project page
Common errors and how to fix them
Unable to begin: 1.Please recheck the connection! 2.Please insert the SD card!
The module did not answer. Check TX goes to RX and RX to TX, that the 1 k惟 resistor is in the line to the module鈥檚 RX, that the card is FAT32 with MP3 files on it, and that the module has its own 5 V and GND.
play(1) plays the wrong song
Track numbers follow the order files were copied, not file names. Use numbered folders with playFolder(), or format the card and copy the files one at a time in the order you want.
The speaker buzzes or the module resets at high volume
The amplifier pulls current peaks the board cannot always supply. Power the module from a separate 5 V supply with a shared ground, add a 100 碌F capacitor at its power pins, or lower the volume.
Projects that use DFRobotDFPlayerMini
Built-in projects that include it. Each page has the full sketch and opens in the editor, already wired.
Try DFRobotDFPlayerMini without installing anything
Open the example, change the sketch, and keep your version in a free account.