PlayRtttl

Improved Arduino library version of the RTTTL.pde example code written by Brett Hagman http://www.roguerobotics.com/ bhagman@roguerobotics.com

               

Available as Arduino library "PlayRtttl".

   

If you find this library useful, please give it a star.

🌎 Google Translate

Available as Arduino library "PlayRtttl"

Features

• Plays RTTTL melodies/ringtones from FLASH or RAM.
• Non blocking version.
• Name output function.
• Sample melodies.
• Random play of melodies from array.
• Supports inverted tone pin logic i.e. tone pin is HIGH at playing a pause.
• Accepts even invalid specified RTTTL files found in the wild.
• Supports RTX format - 2 additional parameters: 1. l=<number_of_loops> 2.s=<Style[N|S|C]>).
• Tone style (relation of tone output to note length) and loop count can be set for a melody.

Required resources

Arduino tone() function and thus Timer 2 on Arduino Uno, Nano etc.
updatePlayRtttl() must be repeatedly called to proceed in melody.

YouTube video of the RandomMelody example in action.

WOKWI online simulation of the RandomMelody example.
.

Sample code

Blocking play melody from FLASH

#include <PlayRtttl.h>
const int TONE_PIN = 11;
...
    playRtttlBlockingPGM(TONE_PIN, Bond);
...

Non blocking play

...
    startPlayRtttlPGM(TONE_PIN, TakeOnMe);
    while (updatePlayRtttl()) {
        // your own code here...
        delay(1);
    }
...

RTTTL format

<NameString>:<Option>:(<Option>:)<Note>,<Note>...

Option:

• d=Default duration of a note
• o=Default octave
• b=Beats per minutes of a quarter note
• opt l=Number of loops
• opt s=Style - see "#define RTX_STYLE_CONTINUOUS 'C'" and following above

Note:

• opt duration (1 for a whole, 4 for a quarter note, etc.)
• note (p = pause)
• opt dot to increase duration by half
• opt octave

Example: "Short:d=4,o=3,b=240,s=4:c4,8g,8g,a,g.,b,c4"

Compile options / macros for this library

To customize the library to different requirements, there are some compile options / macros available.
These macros must be defined in your program before the line #include <PlayRtttl.hpp> to take effect.
Modify them by enabling / disabling them, or change the values if applicable.

Name	Default value	Description
USE_NO_RTX_EXTENSIONS	disabled	Disables interpretation of RTX format definitions 's' (style) and 'l' (loop). Even with USE_NO_RTX_EXTENSIONS activated, the default style is natural (Tone length = note length - 1/16). Saves up to 332 bytes program memory.
RTX_STYLE_DEFAULT	'N'	(Natural) Tone length = note length - 1/16.

Changing include (*.h) files with Arduino IDE

First, use Sketch > Show Sketch Folder (Ctrl+K).
If you have not yet saved the example as your own sketch, then you are instantly in the right library folder.
Otherwise you have to navigate to the parallel libraries folder and select the library you want to access.
In both cases the library source and include files are located in the libraries src directory.
The modification must be renewed for each new library version!

Modifying compile options / macros with PlatformIO

If you are using PlatformIO, you can define the macros in the platformio.ini file with build_flags = -D MACRO_NAME or build_flags = -D MACRO_NAME=macroValue.

Modifying compile options / macros with Sloeber IDE

If you are using Sloeber as your IDE, you can easily define global symbols with Properties > Arduino > CompileOptions.

Running with 1 MHz

If running with 1 MHz, e.g on an ATtiny, the millis() interrupt needs so much time, that it disturbes the tone() generation by interrupt. You can avoid this by using a tone pin, which is directly supported by hardware. Look at the appropriate pins_arduino.h, find digital_pin_to_timer_PGM[] and choose pins with TIMER1x entries.

More songs

More RTTTL songs can be found under http://www.picaxe.com/RTTTL-Ringtones-for-Tune-Command/ or ask Google. C array of songs on GitHub

Compiling for ATtinies

In order to fit the examples to the 8K flash of ATtiny85 and ATtiny88, the Arduino library ATtinySerialOut is required for this CPU's.

Revision History

Version 2.2.0

• Converted to use ESP32 version 3.x.

Version 2.1.0

• Add ability to play C8 and beyond.

Version 2.0.1

• Added function isPlayRtttlRunning().

Version 2.0.0

• Renamed PlayRttl.cpp to PlayRttl.hpp.
• Removed macros SUPPORT_RTX_EXTENSIONS and SUPPORT_RTX_FORMAT.

Version 1.4.2

• New example ReactionTimeTestGame.

Version 1.4.1

• Removed blocking wait for ATmega32U4 Serial in examples.

Version 1.4.0

• Supporting direct tone output at pin 11 for ATmega328. Can be used with interrupt blocking libraries for NeoPixel etc.
• Use Print * instead of Stream *.
• Improved non-AVR compatibility.
• New Christmas songs example.

Version 1.3.0

• Support all octaves below 8
• New styles '1' to '9' in addition to RTX styles 'C', 'N', 'S'.

Version 1.2.2

• Tested with ATtiny85 and 167.
• Ported to non AVR architectures.

Version 1.2.1

• Natural is the new default style.
• New RTTTLMelodiesSmall sample array with less entries.
• Parameter now order independent.
• Modified OneMelody example.

Version 1.2.0

• No Serial.print statements in this library anymore, to avoid problems with different Serial implementations.
• Function playRandomRtttlBlocking() + startPlayRandomRtttlFromArrayPGM() do not print name now. If needed, use new functions playRandomRtttlSampleBlockingAndPrintName() + startPlayRandomRtttlFromArrayPGMAndPrintName().
• Printing functions have parameter (..., Stream *aSerial) to print to any serial. Call it (..., &Serial) using [Sloeber]tandard Serial;
• playRandomRtttlBlocking() renamed to playRandomRtttlSampleBlocking() and bug fixing.

Version 1.1.0

• RTX song format support.
• new setNumberOfLoops() and setDefaultStyle() functions.

Version 1.0.0

Initial Arduino library version

CI

The library examples are tested with GitHub Actions for the following boards:

• arduino:avr:uno
• arduino:avr:leonardo
• arduino:avr:mega
• esp8266:esp8266:huzzah:eesz=4M3M,xtal=80
• esp32:esp32:featheresp32:FlashFreq=80
• STMicroelectronics:stm32:GenF1:pnum=BLUEPILL_F103C8