Struct DfPlayer

pub struct DfPlayer<'a, S, T, D>
where
    S: Read + Write + ReadReady,
    T: TimeSource,
    D: DelayNs,
{ /* private fields */ }

Main driver for interfacing with DFPlayer Mini modules

Implementations

impl<'a, S, T, D> DfPlayer<'a, S, T, D>

where S: Read + Write + ReadReady, T: TimeSource, D: DelayNs,

Structure for interacting with the device

pub async fn try_new( port: &'a mut S, feedback_enable: bool, timeout_ms: u64, time_source: T, delay: D, reset_duration_override: Option<u64>, ) -> Result<Self, Error<S::Error>>

Create a new DFPlayer interface

This initializes the driver and performs a robust startup sequence for the DFPlayer module. The serial port must be configured with 9600 baud, 8N1 format before calling this function.

The initialization sequence:

1. Clears any pending data in the receive buffer
2. Sends a reset command and waits for the device to restart
3. Configures SD card as the default media source
4. Sets the volume to a moderate level (15 out of 30)

The function will attempt to continue even if certain initialization steps fail, making it more resilient to communication issues common with these modules.

Arguments

• port - Serial port connected to the DFPlayer module
• feedback_enable - Whether to enable command acknowledgement (set to false if you’re having reliability issues)
• timeout_ms - Timeout for operations in milliseconds
• time_source - Source of time for timeout tracking
• delay - Delay provider for timing operations
• reset_duration_override - Optional override for reset delay duration (ms)

pub async fn read_last_message(&mut self) -> Result<(), Error<S::Error>>

Read and process a message from the DFPlayer module

This function handles the binary protocol parsing, message validation, and stores the last response. It uses a robust state machine to assemble complete messages from potentially fragmented reads, with proper timeout handling and error recovery.

Special handling is provided for reset commands and 8-byte response formats that sometimes occur in feedback mode.

Returns Ok(()) if a valid message was received and processed, or an error. If a module error response was received, returns that specific error.

pub async fn send_command( &mut self, command_data: MessageData, ) -> Result<(), Error<S::Error>>

Send a command to the DFPlayer module

This constructs a properly formatted message, sends it to the device, and then waits for a response or acknowledgement if feedback is enabled. For query commands in non-feedback mode, attempts to read and process responses with multiple retries if needed.

The method calculates the appropriate checksum and handles all aspects of the binary communication protocol.

Arguments

• command_data - The command and parameters to send

pub async fn next(&mut self) -> Result<(), Error<S::Error>>

Play the next track

Sends the command to play the next track in sequence.

pub async fn reset( &mut self, reset_duration_override: Option<u64>, ) -> Result<(), Error<S::Error>>

Reset the DFPlayer module

Sends a reset command to the module and waits for it to restart. The reset command typically causes the module to restart its processor and reinitialize its state.

Special handling is provided for the reset command, as it often won’t receive a response from the module.

Arguments

• reset_duration_override - Optional override for reset delay duration (ms)

pub async fn set_playback_source( &mut self, playback_source: PlayBackSource, ) -> Result<(), Error<S::Error>>

Set the media source for playback

Configures which media source the DFPlayer should use for audio files. This method includes an additional delay after sending the command to allow the module time to switch sources and initialize the file system.

Arguments

• playback_source - The media source to use (SD card, USB, etc.)

pub async fn set_volume(&mut self, volume: u8) -> Result<(), Error<S::Error>>

Set the volume level (0-30)

Configures the output volume of the DFPlayer module. Valid range is 0 (silent) to 30 (maximum volume).

Arguments

• volume - Volume level from 0 (silent) to 30 (maximum)

Errors

Returns Error::BadParameter if the volume is greater than 30.

pub async fn play(&mut self, track: u16) -> Result<(), Error<S::Error>>

Play a specific track by its index number

Starts playback of a track by its numerical index. Track numbers typically start at 1, not 0.

Arguments

• track - Track number (1-2999)

Errors

Returns Error::BadParameter if the track number is greater than 2999.

pub async fn set_equalizer( &mut self, equalizer: Equalizer, ) -> Result<(), Error<S::Error>>

Set the equalizer mode

Configures the audio equalizer preset on the DFPlayer.

Arguments

• equalizer - Equalizer preset to use

pub async fn set_loop_all( &mut self, enable: bool, ) -> Result<(), Error<S::Error>>

Set whether to loop all tracks

Enables or disables looping through all tracks.

Arguments

• enable - Whether to enable looping of all tracks

pub async fn pause(&mut self) -> Result<(), Error<S::Error>>

Pause the current playback

Pauses any currently playing track.

pub async fn resume(&mut self) -> Result<(), Error<S::Error>>

Resume playback

Resumes playback of a paused track.

pub async fn previous(&mut self) -> Result<(), Error<S::Error>>

Play the previous track

Plays the track before the current one in sequence.

pub async fn stop(&mut self) -> Result<(), Error<S::Error>>

Stop all playback

Stops any current playback, including advertisements.

pub async fn play_from_folder( &mut self, folder: u8, track: u8, ) -> Result<(), Error<S::Error>>

Play a track from a specific folder

The DFPlayer supports organizing tracks in folders. This command plays a specific track from a specific folder. Note that the DFPlayer can be very sensitive to folder and track naming. Folders should typically be named with two digits (01-99) and tracks with three digits (001-255).

Arguments

• folder - Folder number (1-99)
• track - Track number within the folder (1-255)

Errors

Returns Error::BadParameter if parameters are out of range.

pub async fn play_loop_folder( &mut self, folder: u8, ) -> Result<(), Error<S::Error>>

Play all tracks in a specific folder in a loop

This command plays all tracks in a specified folder in sequence, and loops back to the first track when the end is reached. The folder names must be formatted with two digits, starting from 01 to 99 and not exceeding 99. With this command, you can store more than 255 tracks in a folder.

Arguments

• folder - Folder number (1-99)

Errors

Returns Error::BadParameter if the folder number is out of range.

pub async fn play_random(&mut self) -> Result<(), Error<S::Error>>

Play tracks in random order

Starts playback in random order from the current source.

pub async fn set_loop_current_track( &mut self, enable: bool, ) -> Result<(), Error<S::Error>>

Set whether to loop the current track

Enables or disables looping of the currently playing track.

Arguments

• enable - Whether to enable looping of the current track

pub async fn query_tracks_sd(&mut self) -> Result<u16, Error<S::Error>>

Query the total number of tracks on the SD card

pub async fn query_tracks_folder( &mut self, folder: u8, ) -> Result<u16, Error<S::Error>>

Query the total number of tracks in a specific folder

pub async fn query_current_track_sd(&mut self) -> Result<u16, Error<S::Error>>

pub async fn query_volume(&mut self) -> Result<u8, Error<S::Error>>

Query the current volume setting

Returns the current volume level (0-30) or an error.

pub async fn query_eq(&mut self) -> Result<u8, Error<S::Error>>

Query the current equalizer setting

Returns the current equalizer setting (0-5) or an error.

pub async fn sleep(&mut self) -> Result<(), Error<S::Error>>

Send the device to sleep mode

Puts the DFPlayer into low-power sleep mode. In this mode, the device will not respond to most commands until woken up.

Note: While in sleep mode, the device will return ModuleError::Sleeping for most commands.

pub async fn wake_up( &mut self, reset_if_needed: bool, reset_duration_override: Option<u64>, ) -> Result<(), Error<S::Error>>

Wake up the device from sleep mode

Attempts to wake up the DFPlayer from sleep mode using the wake up command (0x0B). Since this command is reported to be unreliable on some modules, it can optionally fall back to a reset if specified.

Arguments

• reset_if_needed - Whether to perform a reset if the normal wake up command fails
• reset_duration_override - Optional override for reset delay duration (ms) if reset is used

pub async fn query_status(&mut self) -> Result<u8, Error<S::Error>>

Query the current status of the device

Returns the current status byte or an error. The status byte indicates:

• If a USB disk is inserted (0x01)
• If a TF card is inserted (0x02)
• If a USB flash drive is inserted (0x04)
• If the device is playing (0x08)
• If the device is paused (0x10)

The returned value is a combination (binary OR) of these flags.