esphome-docs/components/dfplayer.rst

DF-Player mini
==============

.. seo::
    :description: Instructions for setting up DF Player Mini component in ESPHome.
    :image: dfplayer.svg

The ``dfplayer`` (`datasheet <https://wiki.dfrobot.com/DFPlayer_Mini_SKU_DFR0299>`__), component
allows you to play sound and music stored in an SD card or USB flash drive.

.. figure:: images/dfplayer-full.jpg
    :align: center
    :width: 50.0%

    DF-Player mini Module.

For this component to work you need to have set up a :ref:`UART bus <uart>` in your configuration.

Overview
--------

The module can be powered by the 3.3V output of a NodeMCU. For communication 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``.
For best quality audio a powered stereo speaker can be connected to the modules ``DAC_R``,
``DAC_L`` and ``GND``, alternatively the module features a built-in 3W audio amplifier, in that case
the pins ``SPK_1`` and ``SPK_2`` should be connected to one passive speaker and a 5V 1A power supply
will be required.

.. code-block:: yaml

    # Example configuration entry
    dfplayer:

Configuration variables:
------------------------

- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the UART hub.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **on_finished_playback** (*Optional*, :ref:`Automation <automation>`): An action to be
  performed when playback is finished.

``dfplayer.is_playing`` Condition
---------------------------------

This Condition returns true while playback is active.

.. code-block:: yaml

    # 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.

.. code-block:: yaml

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

``dfplayer.play_previous`` Action
---------------------------------

Plays the previously played track.

.. code-block:: yaml

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


``dfplayer.play`` Action
------------------------

Plays a track.

.. code-block:: yaml

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

Configuration options:

- **file** (*Optional*, int, :ref:`templatable <config-templatable>`): The global track
  number (from all tracks in the device). If not specified plays the first track.
- **loop** (*Optional*, boolean, :ref:`templatable <config-templatable>`): Repeats playing
  the same track. Defaults to ``false``.

``dfplayer.play_mp3`` Action
----------------------------

Plays a track inside the folder ``mp3``. Files inside the folder must be numbered from 1
to 9999, like ``0001.mp3``, ``0002.mp3``, ... etc.
The folder name needs to be ``mp3``, placed under the SD card root directory, and the
mp3 file name needs to be 4 digits, for example, "0001.mp3", placed under the mp3 folder.
If you want, you can add additional text after the number in the filename, for example,
``0001hello.mp3``, but must always be referenced by number only in yaml.

.. code-block:: bash

    /mp3
      /0001hello.mp3
      /0002.mp3
      /0003_thisistheway.mp3
      ..

.. code-block:: yaml

    on_...:
      then:
        - dfplayer.play_mp3:
            file: 1
        # Shorthand
        - dfplayer.play_mp3: 1

Configuration options:

- **file** (**Required**, int, :ref:`templatable <config-templatable>`): The file number
  inside the ``mp3`` folder to play.


``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.

.. code-block:: bash

    /01
      /001.mp3
      /002.mp3
      ..
    /02
      /001.mp3
      /002.mp3
      /003.mp3
      ..

.. code-block:: yaml

    on_...:
      then:
        - dfplayer.play_folder:
            folder: 2
            file: 1


Configuration options:

- **folder** (**Required**, int, :ref:`templatable <config-templatable>`): The folder number.
- **file** (*Optional*, int, :ref:`templatable <config-templatable>`): The file number
  inside the folder to play. Optional only if ``loop`` is not set.
- **loop** (*Optional*, boolean, :ref:`templatable <config-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``.

.. code-block:: yaml

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

``dfplayer.set_volume`` Action
------------------------------

Changes volume.

.. code-block:: yaml

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

Configuration options:

- **volume** (**Required**, int, :ref:`templatable <config-templatable>`): The volume value.
  Valid values goes from ``0`` to ``30``.

``dfplayer.volume_up`` Action
-----------------------------

Turn volume up.

.. code-block:: yaml

    on_...:
      then:
        - dfplayer.volume_up

``dfplayer.volume_down`` Action
-------------------------------

Turn volume down.

.. code-block:: yaml

    on_...:
      then:
        - dfplayer.volume_down

``dfplayer.set_eq`` Action
--------------------------

Changes audio equalization preset.

.. code-block:: yaml

    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.

.. code-block:: yaml

    on_...:
      then:
        - dfplayer.sleep

``dfplayer.reset`` Action
-------------------------

Module reset.

.. code-block:: yaml

    on_...:
      then:
        - dfplayer.reset

``dfplayer.start`` Action
-------------------------

Starts playing a track or resumes paused playback.

.. code-block:: yaml

    on_...:
      then:
        - dfplayer.start

``dfplayer.pause`` Action
-------------------------

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

.. code-block:: yaml

    on_...:
      then:
        - dfplayer.pause

``dfplayer.stop`` Action
------------------------

Stops playback.

.. code-block:: yaml

    on_...:
      then:
        - dfplayer.stop


``dfplayer.random`` Action
--------------------------

Randomly plays all tracks.

.. code-block:: yaml

    on_...:
      then:
        - dfplayer.random

All actions
-----------

- **id** (*Optional*, :ref:`config-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

.. code-block:: json

    { "file": 23 }

Sample code
***********

.. code-block:: yaml

    uart:
      tx_pin: GPIOXX
      rx_pin: GPIOXX
      baud_rate: 9600

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

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

      - action: dfplayer_play_loop_folder
        variables:
          folder: int
        then:
          - dfplayer.play_folder:
              folder: !lambda 'return folder;'
              loop: true

      - action: dfplayer_set_device_tf
        then:
          - dfplayer.set_device: TF_CARD

      - action: dfplayer_set_device_usb
        then:
          - dfplayer.set_device: USB

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

      - action: dfplayer_sleep
        then:
          - dfplayer.sleep

      - action: dfplayer_reset
        then:
          - dfplayer.reset

      - action: dfplayer_start
        then:
          - dfplayer.start

      - action: dfplayer_pause
        then:
          - dfplayer.pause

      - action: dfplayer_stop
        then:
          - dfplayer.stop

      - action: dfplayer_random
        then:
          - dfplayer.random

      - action: dfplayer_volume_up
        then:
          - dfplayer.volume_up

      - action: dfplayer_volume_down
        then:
          - dfplayer.volume_down

See Also
--------

- :apiref:`dfplayer/dfplayer.h`
- :ghedit:`Edit`