DF-Player mini

The dfplayer (datasheet), component allows you to play sound and music stored in SD card.

../_images/dfplayer-full.jpg

DF-Player mini Module.

For this integration to work you need to have set up a UART bus in your configuration.

Overview

The module can be powered by the 3V output of an NodeMCU and a powered speaker connected to the modules DAC_R, DAC_I and GND . You can connect only the tx_pin of the uart bus to the module’s RX but if you need feedback of playback active you will also need to connect the rx_pin to the module’s TX.

# Example configuration entry
uart:
  tx_pin: GPIO2
  rx_pin: GPIO5
  baud_rate: 9600

# Declare DFPlayer mini module
dfplayer:
  on_finished_playback:
    then:
      logger.log: 'Somebody press play!'

Configuration variables:

  • uart_id (Optional, ID): Manually specify the ID of the UART hub.
  • id (Optional, ID): Manually specify the ID used for code generation.
  • on_finished_playback (Optional, Automation): An action to be performed when playback is finished.

dfplayer.is_playing Condition

This Condition returns true while playback is active.

# In some trigger:
on_...:
  if:
    condition:
      dfplayer.is_playing
    then:
      logger.log: 'Playback is active!'

dfplayer.play_next Action

Starts playback of next track or skips to the next track.

on_...:
  then:
    - dfplayer.play_next:

dfplayer.play_previous Action

Plays the previously played track.

on_...:
  then:
    - dfplayer.play_previous:

dfplayer.play Action

Plays a track.

on_...:
  then:
    - dfplayer.play:
      file: 23
      loop: false
    # Shorthand
    - dfplayer.play: 23

Configuration options:

  • file (Optional, int, templatable): The global track number (from all tracks in the device). If not specified plays the first track.
  • loop (Optional, bool, templatable): Repeats playing the same track. Defaults to False.

dfplayer.play_folder Action

Plays files inside numbered folders, folders must be numbered from 1 and with leading zeros. Like 01, 02, … etc. Files inside the folders must be numbered with two leading zeros, like 001.mp3, 002.mp3, … etc. Folder numbers can range from 1 to 99 and file name from 1 to 255 or folder number from 1 to 10 and file number from 1 to 1000.

/01
  /001.mp3
  /002.mp3
  ..
/02
  /001.mp3
  /002.mp3
  /003.mp3
  ..
on_...:
  then:
    - dfplayer.play_folder:
        folder: 2
        file: 1

Configuration options:

  • folder (Required, int, templatable): The folder number.
  • file (Optional, int, templatable): The file number inside the folder to play. Optional only if loop is not set.
  • loop (Optional, bool, templatable): Repeats playing all files in the folder. Causes file to be ignored. Defaults to False.

dfplayer.set_device Action

Changes the device in use. Valid values are TF_CARD and USB. Note: only TF_CARD is tested. If you connect a USB stick and found it works please create an issue at ESPHome GitHub.

on_...:
  then:
    - dfplayer.set_device: TF_CARD

dfplayer.set_volume Action

Changes volume.

on_...:
  then:
    - dfplayer.set_volume:
        volume: 20
    # Shorthand
    - dfplayer.set_volume: 20

Configuration options:

  • volume (Required, int, templatable): The volume value. Valid values goes from 0 to 30.

dfplayer.set_eq Action

Changes audio equalization preset.

on_...:
  then:
    - dfplayer.set_eq:
        eq_preset: ROCK
    # Shorthand
    - dfplayer.set_eq: ROCK

Configuration options:

  • eq_preset (Required): Eq Preset value. Valid values are NORMAL, POP, ROCK, JAZZ, CLASSIC and BASS.

dfplayer.sleep Action

Enters sleep mode. Playback is stopped and the action dfplayer.set_device: TF_CARD should be send for playback to be enabled again.

on_...:
  then:
    - dfplayer.sleep

dfplayer.reset Action

Module reset.

on_...:
  then:
    - dfplayer.reset

dfplayer.start Action

Starts playing a track or resumes paused playback.

on_...:
  then:
    - dfplayer.start

dfplayer.pause Action

Pauses playback, playback can be resumed from the same position with dfplayer.start.

on_...:
  then:
    - dfplayer.pause

dfplayer.stop Action

Stops playback.

on_...:
  then:
    - dfplayer.stop

dfplayer.random Action

Randomly plays all tracks.

on_...:
  then:
    - dfplayer.random

All actions

  • id (Optional, ID): Manually specify the ID of the DFPlayer if you have multiple components.

Test setup

With the following code you can quickly setup a node and use Home Assistant’s service in the developer tools. E.g. for calling dfplayer.play_folder select the service esphome.test_node_dfplayer_play and in service data enter

{ "file": 23 }

Sample code

esphome:
  name: test_node
  platform: ESP8266
  board: nodemcu

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_pass

logger:
  level: VERBOSE

uart:
  tx_pin: GPIO2
  rx_pin: GPIO5
  baud_rate: 9600

dfplayer:
  on_finished_playback:
    then:
      logger.log: 'Playback finished event'

api:
  services:
  - service: dfplayer_next
    then:
      - dfplayer.play_next:
  - service: dfplayer_previous
    then:
      - dfplayer.play_previous:
  - service: dfplayer_play
    variables:
      file: int
    then:
      - dfplayer.play: !lambda 'return file;'
  - service: dfplayer_play_loop
    variables:
      file: int
      loop_: bool
    then:
      - dfplayer.play:
          file: !lambda 'return file;'
          loop: !lambda 'return loop_;'
  - service: dfplayer_play_folder
    variables:
      folder: int
      file: int
    then:
      - dfplayer.play_folder:
          folder: !lambda 'return folder;'
          file: !lambda 'return file;'

  - service: dfplayer_play_loo_folder
    variables:
      folder: int
    then:
      - dfplayer.play_folder:
          folder: !lambda 'return folder;'
          loop: True

  - service: dfplayer_set_device
    variables:
      device: int
    then:
      - dfplayer.set_device:
          device: TF_CARD

  - service: dfplayer_set_volume
    variables:
      volume: int
    then:
      - dfplayer.set_volume: !lambda 'return volume;'
  - service: dfplayer_set_eq
    variables:
      preset: int
    then:
      - dfplayer.set_eq: !lambda 'return static_cast<dfplayer::EqPreset>(preset);'

  - service: dfplayer_sleep
    then:
      - dfplayer.sleep

  - service: dfplayer_reset
    then:
      - dfplayer.reset

  - service: dfplayer_start
    then:
      - dfplayer.start

  - service: dfplayer_pause
    then:
      - dfplayer.pause

  - service: dfplayer_stop
    then:
      - dfplayer.stop

  - service: dfplayer_random
    then:
      - dfplayer.random