This is a fully featured library for interfacing with the DFPlayer Mini MP3 player by DFRobot. It also supports other manufacturer's versions of the module.

📖 API Reference
🌐 Official DFRobot Wiki

Extract the latest release to your MCU's storage. On most platforms /lib/ is on the search path per default and should preferably be used to install libraries to. An example directory may look like this:

lib/
└── dfplayer/
    ├── __init__.py
    └── dfplayer.py
main.py

• MicroPython-installed MCU with UART capabilities
• DFPlayer Mini
• microSD card (FAT16 or FAT32; up to 32 GB)
• Speaker (3 W output power)

For this wiring diagram an ESP32-DevKitC is used. Any MicroPython-supported MCU with RX/TX pins for UART communication should work.

Make sure to connect the RX pin to a TX capable pin on the MCU and vice-versa. Boards with only a single UART bus are hard to develop with, due to that bus usually being used for serial debug communication (the MicroPython REPL). This example uses UART bus id 2 for which the board's default pins are 16 (RX) and 17 (TX).

An additional 1k Ohm resistor can be connected between the RX input of the DFPlayer Mini and the TX pin of the MCU, if commands are sometimes not being acknowledged due to board noise on the MCU.

Either MP3 or WAV files can be played back. For simple use cases, use this file structure:

01/
├── 001.mp3
├── 002.mp3
├── 003.wav
    ...
└── 255.mp3
02/
├── 001_Files-can-have.mp3
├── 002_human-readable.mp3
└── 003_suffixes.mp3
    ...

Folders 01 - 15 can have up to ~3000 files if required.

from asyncio import run
from dfplayer import DFPlayer

async def main():
    df = DFPlayer(2) # using UART id 2
    df.init() # initialize UART connection
    await df.wait_available() # optional; making sure DFPlayer finished booting

    await df.volume(15)
    print("DFPlayer reports volume:", await df.volume())

    await df.play(1, 1) # folder 1, file 1

run(main())

def handle_done(device: int, track_id: int):
    print("Playback ended on storage device: {} (Track ID: {})".format(device, track_id))
df.on_done(handle_done)
df.on_eject(lambda device: print("Device", device, "ejected!"))
df.on_insert(lambda device: print("Device", device, "inserted!"))
df.on_ready(lambda devices: print("Ready! Is the SD-card ready?", bool(devices & df.DEVICE_SDCARD)))

df.init()

done = await df.play(2, 2540)
await done
print("Track done, playing another one.")

done = await df.play(1, 4)