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.

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_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

Returns the number of tracks on the SD card.

This method implements a robust strategy for obtaining track counts:

• Sends the query command and processes immediate responses
• For non-feedback mode, waits for delayed responses with multiple attempts
• Returns 0 if no tracks are found or the count couldn’t be retrieved

The track count retrieval is one of the most timing-sensitive operations of the DFPlayer module and may require multiple attempts.

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.