WebbotLib AVR library
WebbotLib It just does it
  C++ documentation  C documentation


Play a tone to any output pin for a fixed duration or until told to stop.
This will output a square wave of 50% duty cycle to any digital I/O Pin and requires the exclusive use of a timer. Multiple tone generators can be created but each one will require its own timer. In order to allow the output to be sent to any output pin then the pin toggling is done via software and hence the frequency range is limited to the audible spectrum.
Note that you must NOT connect a loudspeaker directly to the output pin as you will blow the pin. The reason being that for +5V micro processor and an 8Ω speaker then the current will be 5/8 = 625mA which is way in excess of the typical 40mA that a typical pin can provide.
The solution is to add a resistor in series with the loudspeaker. A value between 150Ω and 1kΩ would do the trick. Just don't expect a 'ghetto blaster' in terms of volume. For example: for +5v processor and using a 150Ω resistor with an 8Ω speaker then (roughly):
You can mix the outputs of multiple tone players into one speaker by adding a resistor from each output pin to one speaker connection and then connecting the other speaker connection to ground.
Whilst the tone player can play a range of different frequencies then there are some shortcuts defined in tone.h for different musical notes/octaves. Open up that file to see what they are called.
To create and use a single tone player using timer 2 to pin B0 then:
#include <tone.h>
Then initialise the player in appInitHardware:
toneInit( &tone1 );
You can now use the remaining calls to play/stop tones.




MAKE_TONE_PLAYER(const Timer* timer, const IOPin* pin)

Creates a new tone player.
The first parameter specifies the timer which will be exclusively used by the tone generator.
The second parameter can be any output pin and is the pin where the frequency signal will be output.

toneInit(TONE_PLAYER* player)

Initialise the tone player.
This will configure the timer ready for use and make sure that the same timer is not being used for other things. It should be called from within your appInitHardware.

tonePlay(TONE_PLAYER* player, uint16_t frequency, uint32_t durationMS )

Start playing the specified tone in the background.
The first parameter specifies the TONE_PLAYER you want to use.
The second parameter is the frequency of the tone. See tone.h for some shortcuts for musical notes. You can also add a pause by specifying a frequency of 0.
The final parameter is how long you want the tone to be played in milliseconds. A value of 0 will cause the note to be played continuously until either a new note is played or you call toneStop.

toneStop(TONE_PLAYER* player)

Stop any current output.

boolean toneIsPlaying(const TONE_PLAYER* player)

Returns TRUE if a note is currently being played or FALSE if not.

toneAttach(TONE_PLAYER* player, ToneCallback callback)

Attach a callback routine to be called when the current note has finished playing.
Since the musical tones are played in the background then its useful to be able to add some code that is called automatically when the current note has finished so that you can queue up the next note. That's what this function is for!
The first parameter is the tone player you want to add the callback to and the second parameter is the address of your own routine.
Your routine should be defined with the following return and parameter signature:-
void myCallback(TONE_PLAYER* player){
    ... the previous tone has finished ...
    ... now do what you want to do - including tonePlay to start the next note ...

toneDetach(TONE_PLAYER* player)

Remove any callback registered with this tone player.

tonePlayRTTTL(TONE_PLAYER* player, const prog_char tune[])

Play an entire tune stored in RTTTL format.
The RTTTL format (Ring Tone Text Transfer Language) is a piece of text to represent a simple tune such as those used by hand held phones. See http://en.wikipedia.org/wiki/Ring_Tone_Transfer_Language for more details on the specification.
There are loads of web sites you can use to download free RTTTL files - Google is your friend.
This command allows you to play such a ring tone whilst the rest of your robot code is running.
Here is an example for the Axon:-
#include <tone.h>
// Create the tone player using TIMER1 and outputting to A2
Now initialise the tone library from appInitHardware:-
Now we can play a tune. But before we do so then we need to create the RTTTL data. The first thing to note in the following example is the use of the 'PROGMEM' keyword to make sure that we don't waste precious RAM memory. So here is an example that you can add at the top of your file:-
const char PROGMEM tune[] = "StarWars:d=4,o=5,b=45:32p,32f#,32f#,32f#,8b.,8f#.6,32e6,32d#6,32c#6,8b.6,16f#.6,32e6,32d#6,32c#6,8b.6,16f#.6,32e6,32d#6,32e6,8c#.6,32f#,32f#,32f#,8b.,8f#.6,32e6,32d#6,32c#6,8b.6,16f#.6,32e6,32d#6,32c#6,8b.6,16f#.6,32e6,32d#6,32e6,8c#6";
To play the tune when the robot first starts up then we can add the following to appInitSoftware:-
tonePlayRTTTL(&tone, tune);

Valid XHTML 1.0 Transitional