Buzzer (RTTTL)¶

Internal GPIO handling NORMAL CLIMATE

Introduction¶

RTTTL (Ring Tone [Text] Transfer Language) was developed by Nokia to play more “easy on the ear” melodies as ringtones for mobile phones. The tunes over all characteristics are created by using three different commands:

d - duration

o - octave

b - tempo (beat)

After that the actual tune is then created using standard notes (a, b, c, d, e, f, and g), before the note the duration is set, after the note the octave is set:

<duration><note><octave>

To compose a jingle you separate the notes with a comma.

Specifications:

Output sound

Wiring¶

ESP               Buzzer
GPIO       <-->   I/O

Power
3.3V       <-->   VCC
GND        <-->   GND

Setup¶

No device is needed, generally you use rules to activate different notifications, or you send commands to activate them. Below you find more information on how to do this.

Rules examples¶

From ESP Easy v2.0.0 its possible to play melodies via RTTTL (don’t forget to remove the spaces and replace # with -, this might be fixed in future releases):

http://<ESP IP address>/control?cmd=rtttl,14,:d=4,o=5,b=112:8a,8a,a,8a,8a,a,8a,8c6,8f.,16g,2a,8a-,8a-,8a-.,16a-,8a-,8a,8a.,16a,8a,8g,8g,8a,g,c6

This plays a melody on pin 14.

You can also use these from rules. We use it to let our alarm system give feedback to the user via a piezo speaker.

To make a boot-sound on startup, create a rule like this:

On System#Boot do
  rtttl,14,:d=10,o=6,b=180,c,e,g
endon

A place to find more tunes, all saved as txt files.

Besides RTTTL it’s also possible to play a single tone on a pin, via a buzzer, speaker or piezo element:

http://<ESP IP address>/control?cmd=tone,14,1300,200

Plays a 1300 Hz tone for 200 ms on GPIO-14.

Indicators (recommended settings)¶

No device is needed.

Commands¶

Internal GPIO handling NORMAL CLIMATE

Supported hardware: Buzzer (RTTTL), Piezo element, Speaker (Ringtones etc.)

Command (GPIO/Value)	Extra information
`tone,<gpio>,<tone>,<duration>` GPIO: 12 … 16 Tone: 20 … 13000 Hz Duration: 100 … 15000 msec	You should try to use GPIO 12…16 since these generally aren’t used. The recommended tone range is 20 Hz … 13 kHz. Up-to 40 kHz should be possible to generate, but will be inaudible for humans. Frequencies above 30 kHz are not stable and will likely crash the ESP. Duration is set in ms. N.B. tones with a duration less than 50 msec will be blocking. Longer duration will use the scheduler, which may cause some fluctuations in the duration.
`rtttl,<gpio>,<value>` GPIO: 12 … 16 Value: d=<duration>,o=<octave>,b=<tempo>,<notes…>	You should try to use GPIO 12…16 since these generally aren’t used by ESP internal functions. N.B. Playing a tune is blocking for as long as the tune is playing. Value can be defined like <name_of_melody:duration,octave,beat,notes….> For example: `rtttl,14,test:d=8,o=5,b=180,c6,b,c6,p,g,g-` More RTTTL Ringtone Downloads Since 2023-09-15: The `rtttl` command, by default, now uses the AnyRtttl library, allowing asynchronous handling of the command. This has the advantage of being non-blocking, allowing ESPEasy to handle other tasks while the tune is being played, but comes with the disadvantage of the output possibly being interrupted/delayed by other (possibly blocking) tasks and events, so the music may not play continuously. Also, the previous implementation may not have stopped sound correctly after playing a song, but as this has been corrected, so there is no longer a need to turn off the GPIO after playing a song.

Command (GPIO/Value)

Extra information

tone,<gpio>,<tone>,<duration>

GPIO: 12 … 16

Tone: 20 … 13000 Hz

Duration: 100 … 15000 msec

You should try to use GPIO 12…16 since these generally aren’t used. The recommended tone range is 20 Hz … 13 kHz. Up-to 40 kHz should be possible to generate, but will be inaudible for humans. Frequencies above 30 kHz are not stable and will likely crash the ESP.

Duration is set in ms.

N.B. tones with a duration less than 50 msec will be blocking. Longer duration will use the scheduler, which may cause some fluctuations in the duration.

rtttl,<gpio>,<value>

GPIO: 12 … 16

Value: d=<duration>,o=<octave>,b=<tempo>,<notes…>

You should try to use GPIO 12…16 since these generally aren’t used by ESP internal functions. N.B. Playing a tune is blocking for as long as the tune is playing.

Value can be defined like <name_of_melody:duration,octave,beat,notes….>

For example: rtttl,14,test:d=8,o=5,b=180,c6,b,c6,p,g,g-

More RTTTL Ringtone Downloads

Since 2023-09-15:

The rtttl command, by default, now uses the AnyRtttl library, allowing asynchronous handling of the command. This has the advantage of being non-blocking, allowing ESPEasy to handle other tasks while the tune is being played, but comes with the disadvantage of the output possibly being interrupted/delayed by other (possibly blocking) tasks and events, so the music may not play continuously.

Also, the previous implementation may not have stopped sound correctly after playing a song, but as this has been corrected, so there is no longer a need to turn off the GPIO after playing a song.

Events¶

Event	Example
`RTTTL#Started` Event generated when a melody/song is played using the Async RTTTL method.	on RTTTL#Started do GPIO,13,1 // Turn on LED while playing a song endon
`RTTTL#Finished` Event generated when the playback of a melody/song is finished using the Async RTTTL method.	on RTTTL#Finished do GPIO,13,0 // Turn off LED after playing a song event,nextSong // Select the next song to play endon
`RTTTL#Cancelled` Event generated when the currently playing melody/song is cancelled by starting a new song using the Async RTTTL method.	on RTTTL#Cancelled do GPIO,13,0 // Turn off LED endon

Where to buy¶

Store	Link
AliExpress	Link 1 ($)

$ = affiliate links which will give us some money to keep this project running, thank you for using those.