A small C library to control a DFPlayer mini (or a clone like MP3-TF-16P) with Raspberry Pi Pico or another RP2040-based microcontroller.

The DFPlayer is an inexpensive audio player capable of playing Mp3 and WAV files at different sampling rates.

This library supports the following operations:

• playback of a specific track
• skip to next or previous track
• set volume, set a maximum volume (range is 1-30)
• increase or decrease volume
• set the equalizer to one of six built-in presets
• set playback mode to single play, folder repeat, single repeat, or random
• pause and resume playback
• query player status, id of current track, volume, and total number of tracks available
• send custom commands

The device supports many more commands than this library implements, most of which can be invoked calling dfplayer_write(). For example, to put the device in standby mode you can use:

dfplayer_write(&dfplayer, 0x0A, 0);

Please refer to the DFPlayer datasheet for more info on the available commands.

The many players on the market come with different chips. Some of them (like MH2024K-24K) require a checksum as part of the control message, some (like MH2024K-16SS) require that the checksum is not sent. Call this function in case your specific player has troubles responding to some commands:

dfplayer_set_checksum_tx(false);

A typical setup would have the player read Mp3 files off a microSD card (formatted as FAT-32), with the audio files at the root level and named sequentially starting with four digits. So, for example:

- root
    - 0001-intro.mp3
    - 0002.mp3
    - 0003.mp3

An example application is provided.

In the example, uart1 is used on GPIOs 8 and 9 on the Pico. Another pair of TX/RX pins can be chosen, just be sure to address the correct uart instance when initializing the DFPlayer.

Two distinct DFPlayers can be used simultaneously using both uart0 and uart1.

• Jukephone

• 2025.11.22 - v1.2.2 - Add null pointer checks
• 2023.10.23 - v1.2.1 - Add max volume setting, querying current volume
• 2023.09.30 - v1.2.0 - Add support for more clone variants
• 2023.09.29 - v1.1.1 - Remove blocking delay while querying
• 2023.09.03 - v1.1.0 - Add query function
• 2023.08.29 - v1.0.0 - First release