PololuBuzzer Class Reference

Play beeps and music with the buzzer. More...

#include <PololuBuzzer.h>

Static Public Member Functions
static void	playFrequency (unsigned int freq, unsigned int duration, unsigned char volume)
	Plays the specified frequency for the specified duration. More...
static void	playNote (unsigned char note, unsigned int duration, unsigned char volume)
	Plays the specified note for the specified duration. More...
static void	play (const char *sequence)
	Plays the specified sequence of notes. More...
static void	play (const __FlashStringHelper *sequence)
static void	playFromProgramSpace (const char *sequence)
	Plays the specified sequence of notes from program space. More...
static void	playMode (unsigned char mode)
	Controls whether play() sequence is played automatically or must be driven with playCheck(). More...
static unsigned char	playCheck ()
	Starts the next note in a sequence, if necessary, in PLAY_CHECK mode. More...
static unsigned char	isPlaying ()
	Checks whether a note, frequency, or sequence is being played. More...
static void	stopPlaying ()
	Stops any note, frequency, or melody being played. More...

Detailed Description

Play beeps and music with the buzzer.

The PololuBuzzer library allows various sounds to be played through a buzzer, from simple beeps to complex tunes.

On the ATmega328P/168 boards, this library uses Timer 2 and pin 3 (PD3/OC2B). On ATmega32U4 boards, this library uses Timer 4 and pin 6 (PD7/OC4D). This library will conflict will other libraries that use the same timer or pin.

Note durations are timed using a timer overflow interrupt (TIMER2_OVF/TIMER4_OVF), which will briefly interrupt execution of your main program at the frequency of the sound being played. In most cases, the interrupt-handling routine is very short (several microseconds). However, when playing a sequence of notes in PLAY_AUTOMATIC mode (the default mode) with the play() command, this interrupt takes much longer than normal (perhaps several hundred microseconds) every time it starts a new note. It is important to take this into account when writing timing-critical code.

This library is fully compatible with the OrangutanBuzzer functions in the Pololu AVR C/C++ Library and the ZumoBuzzer library, so any sequences and melodies written for those libraries will also work with the equivalent PololuBuzzer functions.

Definition at line 89 of file PololuBuzzer.h.

Member Function Documentation

isPlaying()

unsigned char PololuBuzzer::isPlaying ( )

static

Checks whether a note, frequency, or sequence is being played.

Returns

1 if the buzzer is current playing a note, frequency, or sequence; 0 otherwise.

This method returns 1 (true) if the buzzer is currently playing a note/frequency or if it is still playing a sequence started by play(). Otherwise, it returns 0 (false). You can poll this method to determine when it's time to play the next note in a sequence, or you can use it as the argument to a delay loop to wait while the buzzer is busy.

Definition at line 411 of file PololuBuzzer.cpp.

play()

void PololuBuzzer::play ( const char *  sequence )

static

Plays the specified sequence of notes.

Parameters

sequence

Char array containing a sequence of notes to play.

If the play mode is PLAY_AUTOMATIC (default), the sequence of notes will play with no further action required by the user. If the play mode is PLAY_CHECK, the user will need to call playCheck() in the main loop to initiate the playing of each new note in the sequence. The play mode can be changed while the sequence is playing. The sequence syntax is modeled after the PLAY commands in GW-BASIC, with just a few differences.

The notes are specified by the characters C, D, E, F, G, A, and B, and they are played by default as "quarter notes" with a length of 500 ms. This corresponds to a tempo of 120 beats/min. Other durations can be specified by putting a number immediately after the note. For example, C8 specifies C played as an eighth note, with half the duration of a quarter note. The special note R plays a rest (no sound). The sequence parser is case-insensitive and ignores spaces, which may be used to format your music nicely.

Various control characters alter the sound:

Control character(s)	Effect
A–G	Specifies a note that will be played.
R	Specifies a rest (no sound for the duration of the note).
+ or # after a note	Raises the preceding note one half-step.
- after a note	Lowers the preceding note one half-step.
1–2000 after a note	Determines the duration of the preceding note. For example, C16 specifies C played as a sixteenth note (1/16th the length of a whole note).
. after a note	"Dots" the preceding note, increasing the length by 50%. Each additional dot adds half as much as the previous dot, so that "A.." is 1.75 times the length of "A".
> before a note	Plays the following note one octave higher.
< before a note	Plays the following note one octave lower.
O followed by a number	Sets the octave. (default: O4)
T followed by a number	Sets the tempo in beats per minute (BPM). (default: T120)
L followed by a number	Sets the default note duration to the type specified by the number: 4 for quarter notes, 8 for eighth notes, 16 for sixteenth notes, etc. (default: L4)
V followed by a number	Sets the music volume (0–15). (default: V15)
MS	Sets all subsequent notes to play play staccato – each note is played for 1/2 of its allotted time, followed by an equal period of silence.
ML	Sets all subsequent notes to play legato – each note is played for full length. This is the default setting.
!	Resets the octave, tempo, duration, volume, and staccato setting to their default values. These settings persist from one play() to the next, which allows you to more conveniently break up your music into reusable sections.

This function plays the string of notes in the background while your program continues to execute. If you call another buzzer function while the melody is playing, the new function call will overwrite the previous and take control of the buzzer. If you want to string melodies together, you should put an appropriate delay after you start a melody playing. You can use the is_playing() function to figure out when the buzzer is through playing the melody.

Example

PololuBuzzer buzzer;
 
...
 
// play a C major scale up and back down:
buzzer.play("!L16 V8 cdefgab>cbagfedc");
while (buzzer.isPlaying());
 
// the first few measures of Bach's fugue in D-minor
buzzer.play("!T240 L8 agafaea dac+adaea fa<aa<bac#a dac#adaea f4");

Definition at line 474 of file PololuBuzzer.cpp.

playCheck()

unsigned char PololuBuzzer::playCheck ( )

static

Starts the next note in a sequence, if necessary, in PLAY_CHECK mode.

Returns

0 if sequence is complete, 1 otherwise.

This method only needs to be called if you are in PLAY_CHECK mode. It checks to see whether it is time to start another note in the sequence initiated by play(), and starts it if so. If it is not yet time to start the next note, this method returns without doing anything. Call this as often as possible in your main loop to avoid delays between notes in the sequence. This method returns 0 (false) if the melody to be played is complete, otherwise it returns 1 (true).

Definition at line 736 of file PololuBuzzer.cpp.

playFrequency()

void PololuBuzzer::playFrequency ( unsigned int  freq, unsigned int  duration, unsigned char  volume  )

static

Plays the specified frequency for the specified duration.

Parameters

freq	Frequency to play in Hz (or 0.1 Hz if the DIV_BY_10 bit is set).
duration	Duration of the note in milliseconds.
volume	Volume of the note (0–15).

The frequency argument must be between 40 Hz and 10 kHz. If the most significant bit of frequency is set, the frequency played is the value of the lower 15 bits of frequency in units of 0.1 Hz. Therefore, you can play a frequency of 44.5 Hz by using a frequency of (DIV_BY_10 | 445). If the most significant bit of frequency is not set, the units for frequency are Hz. The volume argument controls the buzzer volume, with 15 being the loudest and 0 being the quietest. A volume of 15 supplies the buzzer with a 50% duty cycle PWM at the specified frequency. Lowering volume by one halves the duty cycle (so 14 gives a 25% duty cycle, 13 gives a 12.5% duty cycle, etc). The volume control is somewhat crude (especially on the ATmega328/168) and should be thought of as a bonus feature.

This function plays the note in the background while your program continues to execute. If you call another buzzer function while the note is playing, the new function call will overwrite the previous and take control of the buzzer. If you want to string notes together, you should either use the play() function or put an appropriate delay after you start a note playing. You can use the is_playing() function to figure out when the buzzer is through playing its note or melody.

Example

PololuBuzzer buzzer;
 
...
 
// play a 6 kHz note for 250 ms at a lower volume
buzzer.playFrequency(6000, 250, 12);
 
// wait for buzzer to finish playing the note
while (buzzer.isPlaying());
 
// play a 44.5 Hz note for 1 s at full volume
buzzer.playFrequency(DIV_BY_10 | 445, 1000, 15);

Warning

frequency × duration / 1000 must be no greater than 0xFFFF (65535). This means you can't use a duration of 65535 ms for frequencies greater than 1 kHz. For example, the maximum duration you can use for a frequency of 10 kHz is 6553 ms. If you use a duration longer than this, you will produce an integer overflow that can result in unexpected behavior.

Definition at line 199 of file PololuBuzzer.cpp.

playFromProgramSpace()

void PololuBuzzer::playFromProgramSpace ( const char *  sequence )

static

Plays the specified sequence of notes from program space.

Parameters

sequence

Char array in program space containing a sequence of notes to play.

A version of play() that takes a pointer to program space instead of RAM. This is desirable since RAM is limited and the string must be in program space anyway.

Example

#include <avr/pgmspace.h>
 
PololuBuzzer buzzer;
const char melody[] PROGMEM = "!L16 V8 cdefgab>cbagfedc";
 
...
 
buzzer.playFromProgramSpace(melody);

Definition at line 483 of file PololuBuzzer.cpp.

playMode()

void PololuBuzzer::playMode ( unsigned char  mode )

static

Controls whether play() sequence is played automatically or must be driven with playCheck().

Parameters

mode	Play mode (either PLAY_AUTOMATIC or PLAY_CHECK).

This method lets you determine whether the notes of the play() sequence are played automatically in the background or are driven by the playCheck() method. If mode is PLAY_AUTOMATIC, the sequence will play automatically in the background, driven by the timer overflow interrupt. The interrupt will take a considerable amount of time to execute when it starts the next note in the sequence playing, so it is recommended that you do not use automatic-play if you cannot tolerate being interrupted for more than a few microseconds. If mode is PLAY_CHECK, you can control when the next note in the sequence is played by calling the playCheck() method at acceptable points in your main loop. If your main loop has substantial delays, it is recommended that you use automatic-play mode rather than play-check mode. Note that the play mode can be changed while the sequence is being played. The mode is set to PLAY_AUTOMATIC by default.

Definition at line 719 of file PololuBuzzer.cpp.

playNote()

void PololuBuzzer::playNote ( unsigned char  note, unsigned int  duration, unsigned char  volume  )

static

Plays the specified note for the specified duration.

Parameters

note	Note to play (see Note Macros).
duration	Duration of the note in milliseconds.
volume	Volume of the note (0–15).

The note argument is an enumeration for the notes of the equal tempered scale (ETS). See Note Macros for more information. The volume argument controls the buzzer volume, with 15 being the loudest and 0 being the quietest. A volume of 15 supplies the buzzer with a 50% duty cycle PWM at the specified frequency. Lowering volume by one halves the duty cycle (so 14 gives a 25% duty cycle, 13 gives a 12.5% duty cycle, etc). The volume control is somewhat crude (especially on the ATmega328/168) and should be thought of as a bonus feature.

This function plays the note in the background while your program continues to execute. If you call another buzzer function while the note is playing, the new function call will overwrite the previous and take control of the buzzer. If you want to string notes together, you should either use the play() function or put an appropriate delay after you start a note playing. You can use the is_playing() function to figure out when the buzzer is through playing its note or melody.

Definition at line 305 of file PololuBuzzer.cpp.

stopPlaying()

void PololuBuzzer::stopPlaying ( )

static

Stops any note, frequency, or melody being played.

This method will immediately silence the buzzer and terminate any note/frequency/melody that is currently playing.

Definition at line 494 of file PololuBuzzer.cpp.

---

The documentation for this class was generated from the following files:

• src/PololuBuzzer.h
• src/PololuBuzzer.cpp