add buzzer rtttl docs (#700)
* add buzzer rtttl docs * Update components/rtttl.rst * removed references to not supported PWM output
This commit is contained in:
parent
f22ac1a550
commit
af9d511ed3
Binary file not shown.
After Width: | Height: | Size: 37 KiB |
|
@ -0,0 +1,162 @@
|
||||||
|
Rtttl Buzzer
|
||||||
|
============
|
||||||
|
|
||||||
|
.. seo::
|
||||||
|
:description: Instructions for setting up a buzzer to play tones and rtttl songs with ESPHome.
|
||||||
|
:image: crosshair-gps.png
|
||||||
|
|
||||||
|
The ``rtttl``, component allows you to easily connect a passive piezo buzzer to your microcontroller
|
||||||
|
and play monophonic songs. It accepts the Ring Tone Text Transfer Language, rtttl format (`Wikipedia
|
||||||
|
<https://en.wikipedia.org/wiki/Ring_Tone_Transfer_Language>`__) which allows to store simple melodies.
|
||||||
|
|
||||||
|
.. figure:: images/buzzer.jpg
|
||||||
|
:align: center
|
||||||
|
:width: 50.0%
|
||||||
|
|
||||||
|
Buzzer Module
|
||||||
|
|
||||||
|
Overview
|
||||||
|
--------
|
||||||
|
|
||||||
|
It's important that your buzzer is a **passive** one, if it beeps when you feed it with 3.3V then it is not
|
||||||
|
a passive one and this library will not work properly.
|
||||||
|
|
||||||
|
The tone generator needs a PWM capable output to work with, currently only the
|
||||||
|
:doc:`ESP8266 Software PWM Output<output/esp8266_pwm>` and
|
||||||
|
:doc:`ESP32 LEDC Output <output/ledc>` are supported.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# Example configuration entry
|
||||||
|
output:
|
||||||
|
- platform: ledc
|
||||||
|
pin: GPIO22
|
||||||
|
id: rtttl_out
|
||||||
|
|
||||||
|
rtttl:
|
||||||
|
output: rtttl_out
|
||||||
|
|
||||||
|
Configuration variables:
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
- **output** (**Required**, :ref:`config-id`): The id of the :ref:`float output <output>` to use for
|
||||||
|
this buzzer.
|
||||||
|
- **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.
|
||||||
|
|
||||||
|
|
||||||
|
``rtttl.play`` Action
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Plays an rtttl tone.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
on_...:
|
||||||
|
then:
|
||||||
|
- rtttl.play: 'MissionImp:d=16,o=6,b=95:32d,32d#,32d,32d#,32d,32d#,32d,32d#,32d,32d,32d#,32e,32f,32f#,32g,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,a#,g,2d,32p,a#,g,2c#,32p,a#,g,2c,a#5,8c,2p,32p,a#5,g5,2f#,32p,a#5,g5,2f,32p,a#5,g5,2e,d#,8d'
|
||||||
|
|
||||||
|
Configuration options:
|
||||||
|
|
||||||
|
- **play** (**Required**, string, :ref:`templatable <config-templatable>`): The rtttl string.
|
||||||
|
|
||||||
|
You can find many rtttl strings online on the web, they must start with a name, then a colon: ``:`` symbol
|
||||||
|
and more codes of the song itself. TipÑ you can try playing with the values of d=16,o=6,b=95 and make the
|
||||||
|
song play at a different pace or pitch, e.g. setting o=7 instead will cause the song to play on a higher pitch.
|
||||||
|
|
||||||
|
|
||||||
|
``rtttl.stop`` Action
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Stops playback.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
on_...:
|
||||||
|
then:
|
||||||
|
- rtttl.stop
|
||||||
|
|
||||||
|
All actions
|
||||||
|
-----------
|
||||||
|
|
||||||
|
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the rtttl if you have multiple components.
|
||||||
|
|
||||||
|
``rtttl.is_playing`` Condition
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
This Condition returns true while playback is active.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# In some trigger:
|
||||||
|
on_...:
|
||||||
|
if:
|
||||||
|
condition:
|
||||||
|
rtttl.is_playing
|
||||||
|
then:
|
||||||
|
logger.log: 'Playback is active!'
|
||||||
|
|
||||||
|
|
||||||
|
Common beeps
|
||||||
|
------------
|
||||||
|
|
||||||
|
You can do your own beep patterns too! Here are a few I made so you can just use right away or tweak them to your
|
||||||
|
like:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
two short:d=4,o=5,b=100:16e6,16e6
|
||||||
|
long:d=1,o=5,b=100:e6
|
||||||
|
siren:d=8,o=5,b=100:d,e,d,e,d,e,d,e
|
||||||
|
scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b
|
||||||
|
|
||||||
|
|
||||||
|
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 ``rtttl.play`` select the service ``esphome.test_esp8266_rtttl_play`` and in service data enter
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
song_str: "mario:d=4,o=5,b=100:16e6,16e6,32p,8e6,16c6,8e6,8g6,8p,8g,8p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,16p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16c7,16p,16c7,16c7,p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16d#6,8p,16d6,8p,16c6"
|
||||||
|
|
||||||
|
Sample code
|
||||||
|
***********
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
esphome:
|
||||||
|
name: test_esp8266
|
||||||
|
platform: ESP8266
|
||||||
|
board: nodemcuv2
|
||||||
|
|
||||||
|
wifi:
|
||||||
|
ssid: !secret wifi_ssid
|
||||||
|
password: !secret wifi_pass
|
||||||
|
|
||||||
|
output:
|
||||||
|
- platform: esp8266_pwm
|
||||||
|
pin: D1
|
||||||
|
id: rtttl_out
|
||||||
|
|
||||||
|
rtttl:
|
||||||
|
output: rtttl_out
|
||||||
|
on_finished_playback:
|
||||||
|
- logger.log: 'Song ended!'
|
||||||
|
|
||||||
|
api:
|
||||||
|
services:
|
||||||
|
- service: play_rtttl
|
||||||
|
variables:
|
||||||
|
song_str: string
|
||||||
|
then:
|
||||||
|
- rtttl.play:
|
||||||
|
rtttl: !lambda 'return song_str;'
|
||||||
|
|
||||||
|
See Also
|
||||||
|
--------
|
||||||
|
|
||||||
|
- :apiref:`rtttl/rtttl.h`
|
||||||
|
- :ghedit:`Edit`
|
Binary file not shown.
After Width: | Height: | Size: 9.1 KiB |
|
@ -355,6 +355,7 @@ Misc Components
|
||||||
RF Bridge, components/rf_bridge, rf_bridge.jpg
|
RF Bridge, components/rf_bridge, rf_bridge.jpg
|
||||||
Tuya MCU, components/tuya, tuya.png
|
Tuya MCU, components/tuya, tuya.png
|
||||||
Exposure Notifications, components/exposure_notifications, exposure_notifications.png
|
Exposure Notifications, components/exposure_notifications, exposure_notifications.png
|
||||||
|
RTTTL Buzzer, components/rtttl, buzzer.jpg
|
||||||
|
|
||||||
Additional Custom Components
|
Additional Custom Components
|
||||||
----------------------------
|
----------------------------
|
||||||
|
|
Loading…
Reference in New Issue