Add DFPlayer docs (#306)

* Add DFPlayer docs

* lint


Co-authored-by: Otto Winter <otto@otto-winter.com>

components/dfplayer_mini.rst

@@ -0,0 +1,397 @@
+DF-Player mini
+==============
+
+.. seo::
+    :description: Instructions for setting up DF Player Mini integration in ESPHome.
+    :image: crosshair-gps.png
+
+The ``dfplayer`` (`datasheet <https://wiki.dfrobot.com/DFPlayer_Mini_SKU_DFR0299>`__), component
+allows you to play sound and music stored in SD card.
+
+.. figure:: images/dfplayer-full.jpg
+    :align: center
+    :width: 50.0%
+
+    DF-Player mini Module.
+
+For this integration to work you need to have set up a :ref:`UART bus <uart>`
+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``.
+
+.. code-block:: yaml
+
+    # 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*, :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*, bool, :ref:`templatable <config-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.
+
+.. 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*, bool, :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``. *Note: only* ``TF_CARD``
+*is tested. If you connect a USB stick and found it works please create an issue at ESPHome
+GitHub*.
+
+.. 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.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
+
+    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
+
+See Also
+--------
+
+- :apiref:`dfplayer/dfplayer.h`
+- :ghedit:`Edit`

images/dfplayer.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M0 0h24v24H0z" fill="none"/><path d="M15 6H3v2h12V6zm0 4H3v2h12v-2zM3 16h8v-2H3v2zM17 6v8.18c-.31-.11-.65-.18-1-.18-1.66 0-3 1.34-3 3s1.34 3 3 3 3-1.34 3-3V8h3V6h-5z"/></svg>

index.rst

@@ -309,7 +309,7 @@ Misc Components
     PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg
     MCP230XX I/O Expander, components/mcp230xx, mcp230xx.svg
     SIM800L, components/sim800l, sim800l.jpg
-
+    DFPlayer, components/dfplayer_mini, dfplayer.svg
     Captive Portal, components/captive_portal, wifi-strength-alert-outline.svg
     Debug Component, components/debug, bug-report.svg