Loading...
Searching...
No Matches
DFPlayer Mini MP3 Player

Driver for the DFPlayer Mini MP3 Player. More...

Detailed Description

Driver for the DFPlayer Mini MP3 Player.

The DFPlayer Mini is a super cheap MP3 Player that can be controlled via UART. It can play files from SD card, USB storage devices and NOR flash. It has an integrated 3W amplifier that can be used to build a standalone mono speaker. Alternatively a stereo output can be used that can be directly connected to headphones, but needs a dedicated amplifier for connecting to passive speakers.

DFPlayer pinout

File System Setup

The SD card or USB storage devices needs to be formatted as FAT32 and the MP3 files have to be stored using one of the following naming schemes, if selecting the files efficiently is required:

Numbered File Inside Numbered Folder Naming Scheme

The MP3 files have to be named with three leading decimal digits (e.g. 001.mp3 or 042 - foo bar.mp3) and must be placed in in folders named with two decimal digits (e.g. 01 or 99). The folder name numbers must be in the range 1-99 and the file name numbers in the range 1-255. Playback of these files can be started using the function dfplayer_play_file .

Examples of valid paths:

Examples of INVALID paths:

Numbered File Inside MP3 Folder Naming Scheme

The MP3 files have to be named with four decimal digits and must be placed in the folder "MP3". Subsequent characters after the four digits are ignored. Valid names are e.g. MP3/0001.mp3 or MP3/0042 - My favorite song.mp3. The file numbers 1-9999 are valid. Playback of these files can be started using the function dfplayer_play_from_mp3 .

Advertisements

MP3 files placed in the folder "ADVERT" named with four decimal digits (e.g. "0001.mp3" or "1337.mp3") can be played as advertisements: The function dfplayer_play_from_advert can be used to start their playback, but only while a non-advertisement is currently playing. After the advertisement the normal playback is resumed. This feature has been implemented in the hope it is used for features like audible user feedback to controls, rather than playing advertisements.

Combining Naming Schemes

All of the above naming schemes can be used on the same storage device. However, you still have to use to the functions intended to be used with the naming scheme of a specific file in order to be able to play it.

Track Numbers

Warning
Track numbers are a bogus unit in the DFPlayer

Track numbers in the dfplayer revert to the number of the file in the file system. Without preparing the medium played at a very low level, it will be hard to map track numbers to their corresponding songs. If you started playback using dfplayer_play_file or dfplayer_play_from_mp3, you can use dfplayer_get_played_file to get the currently played filed according to the used naming scheme (see section above).

Continuous Playback

The are two options for achieving continuous playback with the DFPlayer Mini: The first is to use dfplayer_shuffle_all or dfplayer_repeat_folder to schedule shuffled playback of all files or repeat playback of a folder, respectively. But keep in mind that any playback command will switch back to normal playback mode.

The second option is to schedule playback of the next file right after the playback of a file has completed. This can be implemented most conveniently by using the callback functions (see dfplayer_set_callbacks). But beware: The callbacks are called in interrupt context and the API of this driver MUST ONLY be used in thread context.

Known Hardware Bugs

Device Bugs Not Handled by the Driver

On some versions of the DFPlayer, any UART communication with the device during playback results in audible and unpleasant glitches. The only solution is to not communicate with the device during playback, as the DFPlayer seems to pause playback for some milliseconds after receiving a command. If the busy pin of the DFPlayer is connected to your board and configured, the function dfplayer_get_state will read the busy pin to detect if the DFPlayer is currently playing. Onlyif according to the busy pin the device is not currently playing, the UART interface is used to detect whether the playback is paused or stopped. Thus, dfplayer_get_state can be used without fearing to cause audio glitches, provided the busy pin is connected and configured. You can use this to poll the state of the DPlayer and issue the commands once playback has completed, or use the callbacks (see dfplayer_set_callbacks) to get notified when playback has completed.

When playback of a file from the "ADVERT" folder is started while the device not playing, or already playing a file from the "ADVERT" folder, the command fails to execute and the DFPlayer stops all playback (if currently playing).

Device Bugs Handled by the Driver

(These bugs are transparently handled by the driver, so users of the driver can safely skip reading this section.)

When playing a file from the MP3 folder or from the ADVERT folder, the DFPlayer acknowledges the command before checking if the file actually exists. If the file does not exist, a second message to indicate the failure is send, but no second message is send on success. If the second message is not received, the driver has to figure out by other means if this is a communication error or indicates that the playback has started. If the busy pin of the DFPlayer is connected and configured, it will be used to verify that the command succeeded. Otherwise, the driver will query the status of the device via UART to confirm that playback started, which can cause audible glitches on some revisions. For those revisions, the busy pin should be really used.

When the DFPlayer completes playback of a file, the next command received is not acknowledged, if it is a control command. Query commands are not affected. The driver works around this bug by querying the volume prior to issuing a control command directly after playback completed.

Some versions of the DFPlayer are not able to handle commands send at high frequency. A delay of 100ms is inserted after every communication with the device to counter this.

Some versions of the DFPlayer have a high chance of ignoring commands. The driver tries up to DFPLAYER_RETRIES (5 be default) times the command before giving up. For that reason, non-idempotent commands supported by the DFPlayer (e.g. increase and decrease volume) are not exposed by the driver, as retrying could result in them being executed more than once. There are idempotent commands that can achieve the same (e.g. the set volume command instead of increase or decrease volume commands) for every non-idempotent command, so this doesn't restrict the feature set of the driver.

Files

file  dfplayer_constants.h
 Constants used in the DFPlayer Mini Driver.
 
file  dfplayer_implementation.h
 Header-only functions of the DFPlayer Mini Device driver.
 
file  dfplayer_internal.h
 Internal functions of DFPlayer Mini Device driver.
 
file  dfplayer_params.h
 Default configuration for the DFPlayer Mini driver.
 
file  dfplayer_types.h
 Types used in the DFPlayer Mini Device Driver.
 
file  dfplayer.h
 DFPlayer Mini Device Driver.
 

Macros

#define DFPLAYER_WAIT_MS   (100U)
 The number of milliseconds to wait after receiving playback of file has completed before starting playback of the next file.
 

Functions

int dfplayer_init (dfplayer_t *dev, const dfplayer_params_t *params)
 Initialize a DFPlayer Mini device descriptor.
 
dfplayer_source_set_t dfplayer_get_sources (dfplayer_t *dev)
 Get the set of available playback sources of the given DFPlayer.
 
int dfplayer_set_callbacks (dfplayer_t *dev, dfplayer_cb_done_t cb_done, dfplayer_cb_src_t cb_src)
 Set/clear the event callbacks of the DFPlayer Mini.
 
static int dfplayer_next (dfplayer_t *dev)
 Start playing the next song in the currently used naming scheme.
 
static int dfplayer_prev (dfplayer_t *dev)
 Start playing the previous song in the currently used naming scheme.
 
int dfplayer_step (dfplayer_t *dev, int step)
 Step forward/backward following the currently used naming scheme.
 
static int dfplayer_set_volume (dfplayer_t *dev, uint8_t volume)
 Sets the volume to the given value.
 
static int dfplayer_set_equalizer (dfplayer_t *dev, dfplayer_eq_t equalizer)
 Apply the given equalizer setting.
 
static int dfplayer_set_source (dfplayer_t *dev, dfplayer_source_t src)
 Apply the given source.
 
static int dfplayer_enter_standby (dfplayer_t *dev)
 Enter standby mode.
 
static int dfplayer_exit_standby (dfplayer_t *dev)
 Exit standby mode.
 
static int dfplayer_play (dfplayer_t *dev)
 Start/resume playing.
 
static int dfplayer_pause (dfplayer_t *dev)
 Pause the playback.
 
int dfplayer_play_file (dfplayer_t *dev, uint8_t folder, uint8_t file)
 Start playing the specified file in the specified folder.
 
int dfplayer_play_from_mp3 (dfplayer_t *dev, uint16_t number)
 Start playing the specified number in the MP3 folder.
 
int dfplayer_play_from_advert (dfplayer_t *dev, uint16_t number)
 Start playing the specified number in the ADVERT folder.
 
static int dfplayer_stop_advert (dfplayer_t *dev)
 Stop playing a file from the ADVERT folder and resume previous playback.
 
static int dfplayer_repeat_folder (dfplayer_t *dev, uint8_t folder)
 Start playing and repeating the specified folder.
 
static int dfplayer_shuffle_all (dfplayer_t *dev)
 Launch shuffle playback of all files.
 
static int dfplayer_repeat (dfplayer_t *dev, bool repeat)
 Enable or disable repeat playback.
 
int dfplayer_get_state (dfplayer_t *dev, dfplayer_state_t *state)
 Query the state of the DFPlayer Mini.
 
static int dfplayer_get_volume (dfplayer_t *dev, uint8_t *volume)
 Query the current volume of the DFPlayer Mini.
 
static int dfplayer_get_equalizer (dfplayer_t *dev, dfplayer_eq_t *equalizer)
 Query the current equalizer setting of the DFPlayer Mini.
 
static int dfplayer_get_mode (dfplayer_t *dev, dfplayer_mode_t *mode)
 Query the current playback mode of the DFPlayer Mini.
 
static int dfplayer_get_version (dfplayer_t *dev, uint16_t *version)
 Query the software version running on the DFPlayer Mini.
 
static int dfplayer_files_usb (dfplayer_t *dev, uint16_t *files)
 Query the number of files on the USB storage device.
 
static int dfplayer_files_sdcard (dfplayer_t *dev, uint16_t *files)
 Query the number of files on the SD card.
 
static int dfplayer_files_flash (dfplayer_t *dev, uint16_t *files)
 Query the number of files on the NOR flash.
 
static int dfplayer_get_fileno_usb (dfplayer_t *dev, uint16_t *fileno)
 Query the selected file on the USB storage device.
 
static int dfplayer_get_fileno_sdcard (dfplayer_t *dev, uint16_t *fileno)
 Query the selected file on the SD card.
 
static int dfplayer_get_fileno_flash (dfplayer_t *dev, uint16_t *fileno)
 Query the selected file on the NOR flash.
 
static dfplayer_file_t dfplayer_get_played_file (dfplayer_t *dev)
 Get the currently played file and the used naming scheme.
 
static int dfplayer_source_set_contains (dfplayer_source_set_t set, dfplayer_source_t src)
 Check if the given source set contains the given source.
 
static void dfplayer_source_set_add (dfplayer_source_set_t *set, dfplayer_source_t src)
 Add the given source to the given source set.
 
static void dfplayer_source_set_rm (dfplayer_source_set_t *set, dfplayer_source_t src)
 Remove the given source to the given source set.
 

Macro Definition Documentation

◆ DFPLAYER_WAIT_MS

#define DFPLAYER_WAIT_MS   (100U)

The number of milliseconds to wait after receiving playback of file has completed before starting playback of the next file.

Definition at line 194 of file dfplayer.h.

Function Documentation

◆ dfplayer_enter_standby()

static int dfplayer_enter_standby ( dfplayer_t dev)
inlinestatic

Enter standby mode.

Parameters
devDevice descriptor of the DFPlayer to control
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_exit_standby()

static int dfplayer_exit_standby ( dfplayer_t dev)
inlinestatic

Exit standby mode.

Parameters
devDevice descriptor of the DFPlayer to control
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_files_flash()

static int dfplayer_files_flash ( dfplayer_t dev,
uint16_t *  files 
)
inlinestatic

Query the number of files on the NOR flash.

Parameters
devDevice descriptor of the DFPlayer to query
filesThe number of files will be stored here
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_files_sdcard()

static int dfplayer_files_sdcard ( dfplayer_t dev,
uint16_t *  files 
)
inlinestatic

Query the number of files on the SD card.

Parameters
devDevice descriptor of the DFPlayer to query
filesThe number of files will be stored here
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_files_usb()

static int dfplayer_files_usb ( dfplayer_t dev,
uint16_t *  files 
)
inlinestatic

Query the number of files on the USB storage device.

Parameters
devDevice descriptor of the DFPlayer to query
filesThe number of files will be stored here
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_get_equalizer()

static int dfplayer_get_equalizer ( dfplayer_t dev,
dfplayer_eq_t equalizer 
)
inlinestatic

Query the current equalizer setting of the DFPlayer Mini.

Parameters
devDevice descriptor of the DFPlayer to query
equalizerThe equalizer setting will be stored here
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_get_fileno_flash()

static int dfplayer_get_fileno_flash ( dfplayer_t dev,
uint16_t *  fileno 
)
inlinestatic

Query the selected file on the NOR flash.

Warning
The file number refers to the internal file system order
Parameters
devDevice descriptor of the DFPlayer to query
filenoThe selected file will be stored here
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_get_fileno_sdcard()

static int dfplayer_get_fileno_sdcard ( dfplayer_t dev,
uint16_t *  fileno 
)
inlinestatic

Query the selected file on the SD card.

Warning
The file number refers to the internal file system order
Parameters
devDevice descriptor of the DFPlayer to query
filenoThe selected file will be stored here
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_get_fileno_usb()

static int dfplayer_get_fileno_usb ( dfplayer_t dev,
uint16_t *  fileno 
)
inlinestatic

Query the selected file on the USB storage device.

Warning
The file number refers to the internal file system order
Parameters
devDevice descriptor of the DFPlayer to query
filenoThe selected file will be stored here
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_get_mode()

static int dfplayer_get_mode ( dfplayer_t dev,
dfplayer_mode_t mode 
)
inlinestatic

Query the current playback mode of the DFPlayer Mini.

Parameters
devDevice descriptor of the DFPlayer to query
modeThe playback mode will be stored here
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_get_played_file()

static dfplayer_file_t dfplayer_get_played_file ( dfplayer_t dev)
inlinestatic

Get the currently played file and the used naming scheme.

Parameters
devDevice descriptor of the DFPlayer to query
Returns
The currently played file and the used naming scheme

◆ dfplayer_get_sources()

dfplayer_source_set_t dfplayer_get_sources ( dfplayer_t dev)

Get the set of available playback sources of the given DFPlayer.

Parameters
devDevice descriptor of the DFPlayer Mini check
Returns
The set of playback sources currently available
Return values
0If dev is NULL or no source is available

◆ dfplayer_get_state()

int dfplayer_get_state ( dfplayer_t dev,
dfplayer_state_t state 
)

Query the state of the DFPlayer Mini.

Parameters
devDevice descriptor of the DFPlayer to query
stateThe state will be stored here
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out
Note
This function will work best when the busy pin is connected and and configured, as this can avoid UART communication if the device is currently playing. (Remember that UART communication results in audible glitches during playback...)

◆ dfplayer_get_version()

static int dfplayer_get_version ( dfplayer_t dev,
uint16_t *  version 
)
inlinestatic

Query the software version running on the DFPlayer Mini.

Parameters
devDevice descriptor of the DFPlayer to query
versionThe software version will be stored here
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_get_volume()

static int dfplayer_get_volume ( dfplayer_t dev,
uint8_t *  volume 
)
inlinestatic

Query the current volume of the DFPlayer Mini.

Parameters
devDevice descriptor of the DFPlayer to query
volumeThe volume will be stored here
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_init()

int dfplayer_init ( dfplayer_t dev,
const dfplayer_params_t params 
)

Initialize a DFPlayer Mini device descriptor.

Parameters
devDevice descriptor to initialized
paramsConnection parameters to initialize with
Return values
0Success
-EINVALInvalid parameters
-EIOFailed to initialize UART interface / GPIO pin
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_next()

static int dfplayer_next ( dfplayer_t dev)
inlinestatic

Start playing the next song in the currently used naming scheme.

Parameters
devDevice descriptor of the DFPlayer to control
Return values
0Success
-EINVALCalled with invalid parameter
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out
-ERANGEThe next song is out of range (depending to the currently used naming scheme)
-ENOENTNo such file

If previously dfplayer_play_file was used to start playback of file "42/113.mp3", this call will try to start "42/114.mp3". If previously dfplayer_play_from_mp3 was used to start playback of file "MP3/1337.mp3", this call will try to start "MP3/1338.mp3".

◆ dfplayer_pause()

static int dfplayer_pause ( dfplayer_t dev)
inlinestatic

Pause the playback.

Parameters
devDevice descriptor of the DFPlayer to control
Return values
0Success
-EINVALCalled with invalid parameter
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_play()

static int dfplayer_play ( dfplayer_t dev)
inlinestatic

Start/resume playing.

Parameters
devDevice descriptor of the DFPlayer to control
Return values
0Success
-EINVALCalled with invalid parameter
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_play_file()

int dfplayer_play_file ( dfplayer_t dev,
uint8_t  folder,
uint8_t  file 
)

Start playing the specified file in the specified folder.

Parameters
devDevice descriptor of the DFPlayer to control
folderNumber of the folder
fileNumber of the file
Return values
0Success
-EINVALCalled with invalid parameters (see precondition)
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out
-ENOENTSpecified file and/or folder does not exist
Precondition
0 < folder <= 100 and file > 0

E.g. when called with folder set to 9 and file set to 42, the file "09/042.mp3" is played. Thus, the folder and file names need to follow a specific naming convention in order to be selectable with this function.

◆ dfplayer_play_from_advert()

int dfplayer_play_from_advert ( dfplayer_t dev,
uint16_t  number 
)

Start playing the specified number in the ADVERT folder.

Parameters
devDevice descriptor of the DFPlayer to control
numberNumber of the number in the folder "ADVERT" to play
Return values
0Success
-EINVALCalled with invalid parameters (see precondition)
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out
-ENOENTSpecified number does not exist
Precondition
0 < number <= 9999
Warning
The playback is only started when the DFPlayer is currently playing a non-advert file. The current playback is paused, the advert-file is played, and the previous playback is resumed afterwards
Note
While this feature was obviously added to allow playing advertisements, this function was provided in the best hope it is not used this way.

E.g. when called with number set to 42, the file "ADVERT/0042.mp3" is played. Thus, the folder and file names need to follow a specific naming convention in order to be selectable with this function.

The most obvious use (apart for advertisements :-/) is to use it for audible feedback to control commands. E.g. when the user changes the volume, a short "boing" sound could be played. That would allow the user to perceive the configured volume, even if currently played song is silent while configuring the volume.

◆ dfplayer_play_from_mp3()

int dfplayer_play_from_mp3 ( dfplayer_t dev,
uint16_t  number 
)

Start playing the specified number in the MP3 folder.

Parameters
devDevice descriptor of the DFPlayer to control
numberNumber of the file in the folder "MP3" to play
Return values
0Success
-EINVALCalled with invalid parameters (see precondition)
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out
-ENOENTSpecified number does not exist
Precondition
0 < number <= 9999

E.g. when called with number set to 42, the file "MP3/0042.mp3" is played. Thus, the folder and file names need to follow a specific naming convention in order to be selectable with this function.

◆ dfplayer_prev()

static int dfplayer_prev ( dfplayer_t dev)
inlinestatic

Start playing the previous song in the currently used naming scheme.

Parameters
devDevice descriptor of the DFPlayer to control
Return values
0Success
-EINVALCalled with invalid parameter
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out
-ERANGEThe next song is out of range (depending to the currently used naming scheme)
-ENOENTNo such file

If previously dfplayer_play_file was used to start playback of file "42/113.mp3", this call will try to start "42/112.mp3". If previously dfplayer_play_from_mp3 was used to start playback of file "MP3/1337.mp3", this call will try to start "MP3/1336.mp3".

◆ dfplayer_repeat()

static int dfplayer_repeat ( dfplayer_t dev,
bool  repeat 
)
inlinestatic

Enable or disable repeat playback.

Parameters
devDevice descriptor of the DFPlayer to control
repeatEnable repeat playback?
Return values
0Success
-EINVALCalled with invalid parameters (see precondition)
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out
-ENOENTSpecified file and/or folder does not exist

◆ dfplayer_repeat_folder()

static int dfplayer_repeat_folder ( dfplayer_t dev,
uint8_t  folder 
)
inlinestatic

Start playing and repeating the specified folder.

Parameters
devDevice descriptor of the DFPlayer to control
folderNumber of the folder to play and repeat
Return values
0Success
-EINVALCalled with invalid parameters (see precondition)
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out
-ENOENTSpecified file and/or folder does not exist
Precondition
0 < folder <= 100 and file > 0

◆ dfplayer_set_callbacks()

int dfplayer_set_callbacks ( dfplayer_t dev,
dfplayer_cb_done_t  cb_done,
dfplayer_cb_src_t  cb_src 
)

Set/clear the event callbacks of the DFPlayer Mini.

Parameters
devDevice descriptor of the DFPlayer to update
cb_doneFunction to call when playback of a file/track completed
cb_srcFunction to call when a source was inserted/ejected
Return values
0Success
-EINVALCalled with invalid parameter

Calling with NULL for cb_done and/or for cb_src clears the corresponding callback functions.

Warning
The callbacks are called from interrupt context

◆ dfplayer_set_equalizer()

static int dfplayer_set_equalizer ( dfplayer_t dev,
dfplayer_eq_t  equalizer 
)
inlinestatic

Apply the given equalizer setting.

Parameters
devDevice descriptor of the DFPlayer to control
equalizerThe equalizer setting to apply
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_set_source()

static int dfplayer_set_source ( dfplayer_t dev,
dfplayer_source_t  src 
)
inlinestatic

Apply the given source.

Parameters
devDevice descriptor of the DFPlayer to control
srcThe source to use for playback
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

◆ dfplayer_set_volume()

static int dfplayer_set_volume ( dfplayer_t dev,
uint8_t  volume 
)
inlinestatic

Sets the volume to the given value.

Parameters
devDevice descriptor of the DFPlayer to control
volumeVolume to set (max 30)
Return values
0Success
-EINVALCalled with invalid parameters
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out

If volume is greater than the maximum allowed volume of 30, 30 will be send instead.

◆ dfplayer_shuffle_all()

static int dfplayer_shuffle_all ( dfplayer_t dev)
inlinestatic

Launch shuffle playback of all files.

Parameters
devDevice descriptor of the DFPlayer to control
Return values
0Success
-EINVALCalled with invalid parameters (see precondition)
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out
-ENOENTSpecified file and/or folder does not exist
Warning
Even files in the "ADVERT" folder are played

◆ dfplayer_source_set_add()

static void dfplayer_source_set_add ( dfplayer_source_set_t set,
dfplayer_source_t  src 
)
inlinestatic

Add the given source to the given source set.

Parameters
setSet of sources to add source to
srcSource to add

This function is idempotent

◆ dfplayer_source_set_contains()

static int dfplayer_source_set_contains ( dfplayer_source_set_t  set,
dfplayer_source_t  src 
)
inlinestatic

Check if the given source set contains the given source.

Parameters
setSet of sources to check
srcSource to check for
Return values
0src is NOT part of set
1src IS part of set

◆ dfplayer_source_set_rm()

static void dfplayer_source_set_rm ( dfplayer_source_set_t set,
dfplayer_source_t  src 
)
inlinestatic

Remove the given source to the given source set.

Parameters
setSet of sources to remove the source from
srcSource to remove

This function is idempotent

◆ dfplayer_step()

int dfplayer_step ( dfplayer_t dev,
int  step 
)

Step forward/backward following the currently used naming scheme.

Parameters
devDevice descriptor of the DFPlayer to control
stepSteps to take (negative for previous files)
Return values
0Success
-EINVALCalled with invalid parameter
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out
-ERANGEThe next song is out of range (depending to the currently used naming scheme)
-ENOENTNo such file

Calling with a value of 1 for step is equivalent to dfplayer_next, calling with a value of -1 for step is equivalent to dfplayer_prev. A value of 0 will restart the currently played song

◆ dfplayer_stop_advert()

static int dfplayer_stop_advert ( dfplayer_t dev)
inlinestatic

Stop playing a file from the ADVERT folder and resume previous playback.

Parameters
devDevice descriptor of the DFPlayer to control
Return values
0Success
-EINVALCalled with invalid parameters (see precondition)
-EIOCommunication with the DFPlayer Mini failed
-EAGAINDFPlayer responded with error "Device busy"
-ETIMEDOUTResponse of the DFPlayer timed out