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:

01/001.mp3
19/249 - Nothing Else Matters.mp3

Examples of INVALID paths:

01 - Yngwie Malmsteen/042 - Leonardo.mp3
- The folder name must only consist of two digits, additional chars are not allowed in the folder name
9/42.mp3
- Leading zeros must be added, e.g. 09/042.mp3 would be valid
99/359.mp3
- Folder number out of range (1-255 is valid)

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 .

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

dev	Device descriptor of the DFPlayer to control

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response of the DFPlayer timed out

◆ dfplayer_exit_standby()

static int dfplayer_exit_standby ( dfplayer_t * dev )

inlinestatic

Exit standby mode.

Parameters

dev	Device descriptor of the DFPlayer to control

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to query
files	The number of files will be stored here

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to query
files	The number of files will be stored here

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to query
files	The number of files will be stored here

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to query
equalizer	The equalizer setting will be stored here

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to query
fileno	The selected file will be stored here

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to query
fileno	The selected file will be stored here

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to query
fileno	The selected file will be stored here

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to query
mode	The playback mode will be stored here

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device 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

dev	Device descriptor of the DFPlayer Mini check

Returns: The set of playback sources currently available

Return values

0	If `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

dev	Device descriptor of the DFPlayer to query
state	The state will be stored here

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to query
version	The software version will be stored here

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to query
volume	The volume will be stored here

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor to initialized
params	Connection parameters to initialize with

Return values

0	Success
-EINVAL	Invalid parameters
-EIO	Failed to initialize UART interface / GPIO pin
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to control

Return values

0	Success
-EINVAL	Called with invalid parameter
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response of the DFPlayer timed out
-ERANGE	The next song is out of range (depending to the currently used naming scheme)
-ENOENT	No 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

dev	Device descriptor of the DFPlayer to control

Return values

0	Success
-EINVAL	Called with invalid parameter
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response of the DFPlayer timed out

◆ dfplayer_play()

static int dfplayer_play ( dfplayer_t * dev )

inlinestatic

Start/resume playing.

Parameters

dev	Device descriptor of the DFPlayer to control

Return values

0	Success
-EINVAL	Called with invalid parameter
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to control
folder	Number of the folder
file	Number of the file

Return values

0	Success
-EINVAL	Called with invalid parameters (see precondition)
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response of the DFPlayer timed out
-ENOENT	Specified 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

dev	Device descriptor of the DFPlayer to control
number	Number of the number in the folder `"ADVERT"` to play

Return values

0	Success
-EINVAL	Called with invalid parameters (see precondition)
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response of the DFPlayer timed out
-ENOENT	Specified 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

dev	Device descriptor of the DFPlayer to control
number	Number of the file in the folder `"MP3"` to play

Return values

0	Success
-EINVAL	Called with invalid parameters (see precondition)
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response of the DFPlayer timed out
-ENOENT	Specified 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

dev	Device descriptor of the DFPlayer to control

Return values

0	Success
-EINVAL	Called with invalid parameter
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response of the DFPlayer timed out
-ERANGE	The next song is out of range (depending to the currently used naming scheme)
-ENOENT	No 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

dev	Device descriptor of the DFPlayer to control
repeat	Enable repeat playback?

Return values

0	Success
-EINVAL	Called with invalid parameters (see precondition)
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response of the DFPlayer timed out
-ENOENT	Specified 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

dev	Device descriptor of the DFPlayer to control
folder	Number of the folder to play and repeat

Return values

0	Success
-EINVAL	Called with invalid parameters (see precondition)
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response of the DFPlayer timed out
-ENOENT	Specified 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

dev	Device descriptor of the DFPlayer to update
cb_done	Function to call when playback of a file/track completed
cb_src	Function to call when a source was inserted/ejected

Return values

0	Success
-EINVAL	Called 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

dev	Device descriptor of the DFPlayer to control
equalizer	The equalizer setting to apply

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to control
src	The source to use for playback

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to control
volume	Volume to set (max 30)

Return values

0	Success
-EINVAL	Called with invalid parameters
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response 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

dev	Device descriptor of the DFPlayer to control

Return values

0	Success
-EINVAL	Called with invalid parameters (see precondition)
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response of the DFPlayer timed out
-ENOENT	Specified 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

set	Set of sources to add source to
src	Source 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

set	Set of sources to check
src	Source to check for

Return values

0	`src` is NOT part of `set`
1	`src` 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

set	Set of sources to remove the source from
src	Source 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

dev	Device descriptor of the DFPlayer to control
step	Steps to take (negative for previous files)

Return values

0	Success
-EINVAL	Called with invalid parameter
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response of the DFPlayer timed out
-ERANGE	The next song is out of range (depending to the currently used naming scheme)
-ENOENT	No 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

dev	Device descriptor of the DFPlayer to control

Return values

0	Success
-EINVAL	Called with invalid parameters (see precondition)
-EIO	Communication with the DFPlayer Mini failed
-EAGAIN	DFPlayer responded with error "Device busy"
-ETIMEDOUT	Response of the DFPlayer timed out

Detailed Description

File System Setup

Numbered File Inside Numbered Folder Naming Scheme

Numbered File Inside MP3 Folder Naming Scheme

Advertisements

Combining Naming Schemes

Track Numbers

Continuous Playback

Known Hardware Bugs

Device Bugs Not Handled by the Driver

Device Bugs Handled by the Driver

Files

Macros

Functions

Macro Definition Documentation

◆ DFPLAYER_WAIT_MS

Function Documentation

◆ dfplayer_enter_standby()

◆ dfplayer_exit_standby()

◆ dfplayer_files_flash()

◆ dfplayer_files_sdcard()

◆ dfplayer_files_usb()

◆ dfplayer_get_equalizer()

◆ dfplayer_get_fileno_flash()

◆ dfplayer_get_fileno_sdcard()

◆ dfplayer_get_fileno_usb()

◆ dfplayer_get_mode()

◆ dfplayer_get_played_file()

◆ dfplayer_get_sources()

◆ dfplayer_get_state()

◆ dfplayer_get_version()

◆ dfplayer_get_volume()

◆ dfplayer_init()

◆ dfplayer_next()

◆ dfplayer_pause()

◆ dfplayer_play()

◆ dfplayer_play_file()

◆ dfplayer_play_from_advert()

◆ dfplayer_play_from_mp3()

◆ dfplayer_prev()

◆ dfplayer_repeat()

◆ dfplayer_repeat_folder()

◆ dfplayer_set_callbacks()

◆ dfplayer_set_equalizer()

◆ dfplayer_set_source()

◆ dfplayer_set_volume()

◆ dfplayer_shuffle_all()

◆ dfplayer_source_set_add()

◆ dfplayer_source_set_contains()

◆ dfplayer_source_set_rm()

◆ dfplayer_step()

◆ dfplayer_stop_advert()