# dfplayer

Library for the DFPlayer Mini.

Author | Rob Jansen, Copyright © 2020..2020, all rights reserved.
Adapted-by |
Compiler | 2.5r4

Description

    JAL library for use of the DFPlayer Mini.

Sources

    Inspired by: https://github.com/PowerBroker2/DFPlayerMini_Fast

Notes

    The default serial interface of the DFPlayer Mini is 9600 baud,
           1 stopbit, no parity and no flowcontrol.
           At least one of the JAL serial libraries must be included and
           initialized by the main program with these settings.

Dependencies

No dependency found

## Summary

### Global variables/contants

- `const byte DFPLAYER_EQUALIZER_JAZZ = 3`
- `const byte _DFPLAYER_SET_VOLUME = 0x06`
- `const byte _DFPLAYER_USE_MP3_FOLDER = 0x12`
- `const byte _DFPLAYER_START = 0x7E`
- `const byte _DFPLAYER_GET_FOLDERS = 0x4F`
- `const byte _DFPLAYER_REPEAT_PLAY = 0x11`
- `const byte _DFPLAYER_STOP_ADVERT = 0x15`
- `const byte _DFPLAYER_REPLY = 0x41`
- `const byte DFPLAYER_EQUALIZER_NORMAL = 0`
- `const byte _DFPLAYER_FEEDBACK = 1`
- `const byte DFPLAYER_MODE_REPEAT = 0`
- `const byte _DFPLAYER_STOP = 0x16`
- `const byte _DFPLAYER_EQUALIZER = 0x07`
- `const byte _DFPLAYER_LENGTH = 0x06`
- `const byte _DFPLAYER_GET_STATUS = 0x42`
- `const byte _DFPLAYER_GET_MODE = 0x45`
- `const byte DFPLAYER_MODE_RANDOM = 3`
- `const byte _DFPLAYER_SPEC_FOLDER = 0x0F`
- `const byte DFPLAYER_EQUALIZER_CLASSIC = 4`
- `const byte _DFPLAYER_GET_SD_FILES = 0x48`
- `const byte DFPLAYER_DEVICE_USB = 1`
- `const byte DFPLAYER_MODE_FOLDER_REPEAT = 1`
- `const byte _DFPLAYER_RETRANSMIT = 0x40`
- `const byte _DFPLAYER_PLAYBACK = 0x0D`
- `const byte _DFPLAYER_RESET = 0x0C`
- `const byte DFPLAYER_DEVICE_SLEEP = 4`
- `const byte _DFPLAYER_SET_DAC = 0x1A`
- `const byte DFPLAYER_DEVICE_SD = 2`
- `const byte _DFPLAYER_PLAY = 0x03`
- `const byte _DFPLAYER_GET_VERSION = 0x46`
- `const byte _DFPLAYER_GET_EQUALIZER = 0x44`
- `const byte DFPLAYER_EQUALIZER_BASE = 5`
- `const byte _DFPLAYER_GET_FLASH_FILES = 0x49`
- `var _dfplayer_serial _dfplayer_buffer`
- `const byte _DFPLAYER_RANDOM_ALL = 0x18`
- `const byte _DFPLAYER_START_REPEAT = 1;`
- `const byte _DFPLAYER_STOP_REPEAT = 0;`
- `const byte _DFPLAYER_GET_SD_TRACK = 0x4C`
- `const byte _DFPLAYER_VOLUME_ADJUST = 0x10`
- `const byte _DFPLAYER_SPEC_TRACK_3000 = 0x14`
- `const byte _DFPLAYER_GET_USB_TRACK = 0x4B`
- `const byte _DFPLAYER_MESSAGE_SIZE = 10`
- `const byte DFPLAYER_MODE_SINGLE_REPEAT = 2`
- `const byte _DFPLAYER_GET_FOLDER_FILES = 0x4E`
- `const byte _DFPLAYER_VERSION = 0xFF`
- `const byte _DFPLAYER_END = 0xEF`
- `const byte _DFPLAYER_SLEEP = 0x0A`
- `const byte _DFPLAYER_NO_FEEDBACK = 0`
- `const byte DFPLAYER_DEVICE_AUX = 3`
- `const byte _DFPLAYER_INC_VOLUME = 0x04`
- `const byte _DFPLAYER_PLAYBACK_DEVICE = 0x09`
- `const byte _DFPLAYER_NORMAL = 0x0B`
- `const byte _DFPLAYER_PREVIOUS = 0x02`
- `const byte DFPLAYER_MAX_VOLUME = 30`
- `const byte DFPLAYER_EQUALIZER_POP = 1`
- `const byte _DFPLAYER_NEXT = 0x01`
- `const byte _DFPLAYER_PAUSE = 0x0E`
- `const byte _DFPLAYER_KEEP_ON = 0x4A`
- `const byte DFPLAYER_MODE_PLAY = 4`
- `const byte DFPLAYER_EQUALIZER_ROCK = 2`
- `const byte _DFPLAYER_DEC_VOLUME = 0x05`
- `const byte _DFPLAYER_REPEAT_CURRENT = 0x19`
- `const byte _DFPLAYER_GET_USB_FILES = 0x47`
- `const byte _DFPLAYER_REPEAT_FOLDER = 0x17`
- `const byte DFPLAYER_DEVICE_FLASH = 5`
- `const byte _DFPLAYER_INSERT_ADVERT = 0x13`
- `const byte _DFPLAYER_REPEAT_TRACK = 0x08`
- `const byte _DFPLAYER_GET_VOLUME = 0x43`
- `const byte _DFPLAYER_GET_FLASH_TRACK = 0x4D`
- `const byte _DFPLAYER_SEND_INIT = 0x3F`

### Procedures

- `dfplayer_play_mp3_folder(word in track_number)`
- `dfplayer_play(word in track_number)`
- `dfplayer_stop_repeat_play()`
- `dfplayer_start_repeat_current()`
- `dfplayer_repeat_folder(word in folder_number)`
- `dfplayer_set_playback_source(byte in source)`
- `dfplayer_play_folder(byte in folder_number, byte in track_number)`
- `dfplayer_dac_on()`
- `dfplayer_start_repeat_play()`
- `dfplayer_play_random()`
- `dfplayer_play_advertisement(word in track_number)`
- `dfplayer_repeat_track(word in track_number)`
- `dfplayer_play_previous()`
- `dfplayer_dac_off()`
- `dfplayer_stop_advertisement()`
- `dfplayer_stop_repeat_current()`
- `dfplayer_normal_mode()`
- `dfplayer_pause()`
- `dfplayer_resume()`
- `dfplayer_play_3000_folder(byte in folder_number, word in track_number)`
- `dfplayer_play_next()`
- `dfplayer_set_volume(byte in volume)`
- `dfplayer_reset()`
- `dfplayer_set_equalizer(byte in equalizer)`
- `dfplayer_increment_volume()`
- `dfplayer_decrement_volume()`
- `dfplayer_sleep_mode()`
- `dfplayer_stop()`

Private

- `_dfplayer_send_data()`
- `_dfplayer_flush_serial()`

### Functions

- `dfplayer_get_nr_of_usb_tracks(word out tracks) return bit`
- `dfplayer_is_sleeping() return bit`
- `dfplayer_get_nr_of_folders(word out nr_of_folders) return bit`
- `dfplayer_is_paused() return bit`
- `dfplayer_is_playing() return bit`
- `dfplayer_is_stopped() return bit`
- `dfplayer_get_current_sd_track(word out track) return bit`
- `dfplayer_get_equalizer(byte out equalizer) return bit`
- `dfplayer_get_volume(byte out volume) return bit`
- `dfplayer_get_nr_of_flash_tracks(word out tracks) return bit`
- `dfplayer_get_current_usb_track(word out track) return bit`
- `dfplayer_get_nr_of_sd_tracks(word out tracks) return bit`
- `dfplayer_get_mode(byte out mode) return bit`
- `dfplayer_get_version(byte out version) return bit`
- `dfplayer_get_current_flash_track(word out track) return bit`

Private

- `_dfplayer_message_received(byte in command) return bit`
- `_dfplayer_get_message() return bit`
- `_dfplayer_calculate_checksum() return word`
- `_dfplayer_get_byte(byte out data) return bit`

## API details

### Global variables/contants

- `const byte DFPLAYER_EQUALIZER_JAZZ = 3`

  No documentation found

- `const byte _DFPLAYER_SET_VOLUME = 0x06`

  No documentation found

- `const byte _DFPLAYER_USE_MP3_FOLDER = 0x12`

  No documentation found

- `const byte _DFPLAYER_START = 0x7E`

  No documentation found

- `const byte _DFPLAYER_GET_FOLDERS = 0x4F`

  No documentation found

- `const byte _DFPLAYER_REPEAT_PLAY = 0x11`

  No documentation found

- `const byte _DFPLAYER_STOP_ADVERT = 0x15`

  No documentation found

- `const byte _DFPLAYER_REPLY = 0x41`

  No documentation found

- `const byte DFPLAYER_EQUALIZER_NORMAL = 0`

      Equalizer values.

- `const byte _DFPLAYER_FEEDBACK = 1`

  No documentation found

- `const byte DFPLAYER_MODE_REPEAT = 0`

      Mode values.

- `const byte _DFPLAYER_STOP = 0x16`

  No documentation found

- `const byte _DFPLAYER_EQUALIZER = 0x07`

  No documentation found

- `const byte _DFPLAYER_LENGTH = 0x06`

  No documentation found

- `const byte _DFPLAYER_GET_STATUS = 0x42`

  No documentation found

- `const byte _DFPLAYER_GET_MODE = 0x45`

  No documentation found

- `const byte DFPLAYER_MODE_RANDOM = 3`

  No documentation found

- `const byte _DFPLAYER_SPEC_FOLDER = 0x0F`

  No documentation found

- `const byte DFPLAYER_EQUALIZER_CLASSIC = 4`

  No documentation found

- `const byte _DFPLAYER_GET_SD_FILES = 0x48`

  No documentation found

- `const byte DFPLAYER_DEVICE_USB = 1`

      Playback source values.

- `const byte DFPLAYER_MODE_FOLDER_REPEAT = 1`

  No documentation found

- `const byte _DFPLAYER_RETRANSMIT = 0x40`

  No documentation found

- `const byte _DFPLAYER_PLAYBACK = 0x0D`

  No documentation found

- `const byte _DFPLAYER_RESET = 0x0C`

  No documentation found

- `const byte DFPLAYER_DEVICE_SLEEP = 4`

  No documentation found

- `const byte _DFPLAYER_SET_DAC = 0x1A`

  No documentation found

- `const byte DFPLAYER_DEVICE_SD = 2`

  No documentation found

- `const byte _DFPLAYER_PLAY = 0x03`

  No documentation found

- `const byte _DFPLAYER_GET_VERSION = 0x46`

  No documentation found

- `const byte _DFPLAYER_GET_EQUALIZER = 0x44`

  No documentation found

- `const byte DFPLAYER_EQUALIZER_BASE = 5`

  No documentation found

- `const byte _DFPLAYER_GET_FLASH_FILES = 0x49`

  No documentation found

- `var _dfplayer_serial _dfplayer_buffer`

      Variable used to send and receive data.

- `const byte _DFPLAYER_RANDOM_ALL = 0x18`

  No documentation found

- `const byte _DFPLAYER_START_REPEAT = 1;`

  No documentation found

- `const byte _DFPLAYER_STOP_REPEAT = 0;`

      Repeat play values.

- `const byte _DFPLAYER_GET_SD_TRACK = 0x4C`

  No documentation found

- `const byte _DFPLAYER_VOLUME_ADJUST = 0x10`

      Not specified in all datasheets.

- `const byte _DFPLAYER_SPEC_TRACK_3000 = 0x14`

  No documentation found

- `const byte _DFPLAYER_GET_USB_TRACK = 0x4B`

  No documentation found

- `const byte _DFPLAYER_MESSAGE_SIZE = 10`

      Constants for the serial communication.

- `const byte DFPLAYER_MODE_SINGLE_REPEAT = 2`

  No documentation found

- `const byte _DFPLAYER_GET_FOLDER_FILES = 0x4E`

  No documentation found

- `const byte _DFPLAYER_VERSION = 0xFF`

  No documentation found

- `const byte _DFPLAYER_END = 0xEF`

  No documentation found

- `const byte _DFPLAYER_SLEEP = 0x0A`

  No documentation found

- `const byte _DFPLAYER_NO_FEEDBACK = 0`

  No documentation found

- `const byte DFPLAYER_DEVICE_AUX = 3`

  No documentation found

- `const byte _DFPLAYER_INC_VOLUME = 0x04`

  No documentation found

- `const byte _DFPLAYER_PLAYBACK_DEVICE = 0x09`

  No documentation found

- `const byte _DFPLAYER_NORMAL = 0x0B`

      Not specified in all datasheets.

- `const byte _DFPLAYER_PREVIOUS = 0x02`

  No documentation found

- `const byte DFPLAYER_MAX_VOLUME = 30`

      Volume values. Min is 0.

- `const byte DFPLAYER_EQUALIZER_POP = 1`

  No documentation found

- `const byte _DFPLAYER_NEXT = 0x01`

      Control commands.

- `const byte _DFPLAYER_PAUSE = 0x0E`

  No documentation found

- `const byte _DFPLAYER_KEEP_ON = 0x4A`

  No documentation found

- `const byte DFPLAYER_MODE_PLAY = 4`

  No documentation found

- `const byte DFPLAYER_EQUALIZER_ROCK = 2`

  No documentation found

- `const byte _DFPLAYER_DEC_VOLUME = 0x05`

  No documentation found

- `const byte _DFPLAYER_REPEAT_CURRENT = 0x19`

  No documentation found

- `const byte _DFPLAYER_GET_USB_FILES = 0x47`

  No documentation found

- `const byte _DFPLAYER_REPEAT_FOLDER = 0x17`

  No documentation found

- `const byte DFPLAYER_DEVICE_FLASH = 5`

  No documentation found

- `const byte _DFPLAYER_INSERT_ADVERT = 0x13`

  No documentation found

- `const byte _DFPLAYER_REPEAT_TRACK = 0x08`

  No documentation found

- `const byte _DFPLAYER_GET_VOLUME = 0x43`

  No documentation found

- `const byte _DFPLAYER_GET_FLASH_TRACK = 0x4D`

  No documentation found

- `const byte _DFPLAYER_SEND_INIT = 0x3F`

      Query commands.

### Procedures

- `dfplayer_play_mp3_folder(word in track_number)`

      Play the given track from the MP3 folder. Track number in range 1 to 3000.

- `dfplayer_play(word in track_number)`

      Play the given track. The track number must be in range 1 to the number
      returned by the function dfplayer_get_nr_of_..._tracks().

- `dfplayer_stop_repeat_play()`

      Stop the repeat playback of all tracks

- `dfplayer_start_repeat_current()`

      Start the repeat of the current track.

- `dfplayer_repeat_folder(word in folder_number)`

      Set repeat of the given folder.

- `dfplayer_set_playback_source(byte in source)`

      Set the playback source.

- `dfplayer_play_folder(byte in folder_number, byte in track_number)`

      Play the given track in the given folder. Folder number in range 1 to 99,
      track number in range 1 to 255.

- `dfplayer_dac_on()`

      Switch the DAC on (is on by default).

- `dfplayer_start_repeat_play()`

      Start the repeat playback of all tracks

- `dfplayer_play_random()`

      Play random.

- `dfplayer_play_advertisement(word in track_number)`

      Play Advertisement.

- `dfplayer_repeat_track(word in track_number)`

      Set repeat of the given track.

- `dfplayer_play_previous()`

      Play the previous track.

- `dfplayer_dac_off()`

      Switch the DAC off (is on by default).

- `dfplayer_stop_advertisement()`

  No documentation found

- `dfplayer_stop_repeat_current()`

      Stop the repeat of the current track.

- `dfplayer_normal_mode()`

      Put the DFPlayer in normal operation mode. This feature is not specified in
      all data sheets and its operation is not defined.

- `dfplayer_pause()`

      Pause the DFPlayer.

- `dfplayer_resume()`

      Resume playback of the DFPlayer.

- `dfplayer_play_3000_folder(byte in folder_number, word in track_number)`

      Play the given track in the special 3000 track given folder. Folder must
      be in range 1 to 15 and track in range 0001 to 3000.

- `dfplayer_play_next()`

      Play the next track.

- `dfplayer_set_volume(byte in volume)`

      Set the volume of the DFPlayer. Must be in range 0 .. DFPLAYER_MAX_VOLUME

- `dfplayer_reset()`

      Reset the DFPlayer and give the DFPlayer sufficient time to initialize.
      Note that dfplayer_reset() and dfplayer_init() are the same.

- `dfplayer_set_equalizer(byte in equalizer)`

      Set the equalizer of the DFPlayer. Parameter must be one of the equalizer modes.

- `dfplayer_increment_volume()`

      Increment the volume of the DFPlayer.

- `dfplayer_decrement_volume()`

      Decrement the volume of the DFPlayer.

- `dfplayer_sleep_mode()`

      Put the DFPlayer in sleep mode. Note the DFPlayer can only be re-activated
      again by switching the power off and on again.

- `dfplayer_stop()`

      Stop playing a track.

Private

- `_dfplayer_send_data()`

      Prepare the data to send and send the data to the DFPlayer.

- `_dfplayer_flush_serial()`

      Flush any data from the serial port.

### Functions

- `dfplayer_get_nr_of_usb_tracks(word out tracks) return bit`

      Return the numner of tracks on the USB device of the DFPlayer.Note that the
      track number returned is a count starting from the first folder. Function
      returns TRUE if succesful.

- `dfplayer_is_sleeping() return bit`

      Check if the DFPlayer is sleepting and return TRUE if so.

- `dfplayer_get_nr_of_folders(word out nr_of_folders) return bit`

      Return the number of folders of the DFPlayer. Function returns TRUE if succesful.

- `dfplayer_is_paused() return bit`

      Check if the DFPlayer is paused and return TRUE if so.

- `dfplayer_is_playing() return bit`

      Check if the DFPlayer is playing and return TRUE if so.

- `dfplayer_is_stopped() return bit`

      Check if the DFPlayer is stopped and return TRUE if so.

- `dfplayer_get_current_sd_track(word out track) return bit`

      Return the current track on the SD device of the DFPlayer. Function returns
      TRUE if succesful.

- `dfplayer_get_equalizer(byte out equalizer) return bit`

      Return the current equalizer setting of the DFPlayer. Function returns TRUE
      if succesful.

- `dfplayer_get_volume(byte out volume) return bit`

      Return the current volume of the DFPlayer. Function returns TRUE if succesful.

- `dfplayer_get_nr_of_flash_tracks(word out tracks) return bit`

      Return the numner of tracks on the Flash device of the DFPlayer. Note that the
      track number returned is a count starting from the first folder. Function
      returns TRUE if succesful.

- `dfplayer_get_current_usb_track(word out track) return bit`

      Return the current track from the USB device of the DFPlayer. Function
      returns TRUE if succesful.

- `dfplayer_get_nr_of_sd_tracks(word out tracks) return bit`

      Return the numner of tracks on the SD device of the DFPlayer. Note that the
      track number returned is a count starting from the first folder. Function
      returns TRUE if succesful.

- `dfplayer_get_mode(byte out mode) return bit`

      Return the current mode setting of the DFPlayer. Function returns TRUE if
      succesful.

- `dfplayer_get_version(byte out version) return bit`

      Return the current version of the DFPlayer. Function returns TRUE if succesful.

- `dfplayer_get_current_flash_track(word out track) return bit`

      Return the current track on the Flash device of the DFPlayer. Function
      returns TRUE if succesful.

Private

- `_dfplayer_message_received(byte in command) return bit`

      Get and check one message from the DFPlayer and return TRUE when
      a valid message is received on the given command

- `_dfplayer_get_message() return bit`

      Get one message from the DFPLayer and return TRUE when received.

- `_dfplayer_calculate_checksum() return word`

      Calculate and return the checksum. It is two's complement.

- `_dfplayer_get_byte(byte out data) return bit`

      Get one byte from the DFPlayer and return TRUE when received. If no data is
      available FALSE is returned.

## Related samples

Here are the list of samples which use this library:

12f617 | 12f617_dfplayer.jal
16f1823 | 16f1823_dfplayer.jal
16f19176 | 16f19176_dfplayer.jal