/*! \file ZumoBuzzer.h
*
* See the ZumoBuzzer class reference for more information about this library.
*
* \class ZumoBuzzer ZumoBuzzer.h
* \brief Play beeps and music with buzzer
*
* The ZumoBuzzer library allows various sounds to be played through the buzzer
* on the Zumo Shield, from simple beeps to complex tunes. The buzzer is
* controlled using a PWM output of Timer 2 (on the Arduino Uno and other
* ATmega328/168 boards) or Timer 4 (on the Arduino Leonardo and other
* ATmega32U4 boards), so it will conflict with any other uses of that timer.
*
* 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.
*
* The ZumoBuzzer library is fully compatible with the OrangutanBuzzer functions
* in the [Pololu AVR C/C++ Library](http://www.pololu.com/docs/0J18), so any
* sequences and melodies written for OrangutanBuzzer functions will also work
* with the equivalent ZumoBuzzer functions.
*/
#ifndef ZumoBuzzer_h
#define ZumoBuzzer_h
#define PLAY_AUTOMATIC 0
#define PLAY_CHECK 1
// n
// Equal Tempered Scale is given by f = f * a
// n o
//
// where f is chosen as A above middle C (A4) at f = 440 Hz
// o o
// and a is given by the twelfth root of 2 (~1.059463094359)
/*! \anchor note_macros
*
* \name Note Macros
* \a x specifies the octave of the note
* @{
*/
#define NOTE_C(x) ( 0 + (x)*12)
#define NOTE_C_SHARP(x) ( 1 + (x)*12)
#define NOTE_D_FLAT(x) ( 1 + (x)*12)
#define NOTE_D(x) ( 2 + (x)*12)
#define NOTE_D_SHARP(x) ( 3 + (x)*12)
#define NOTE_E_FLAT(x) ( 3 + (x)*12)
#define NOTE_E(x) ( 4 + (x)*12)
#define NOTE_F(x) ( 5 + (x)*12)
#define NOTE_F_SHARP(x) ( 6 + (x)*12)
#define NOTE_G_FLAT(x) ( 6 + (x)*12)
#define NOTE_G(x) ( 7 + (x)*12)
#define NOTE_G_SHARP(x) ( 8 + (x)*12)
#define NOTE_A_FLAT(x) ( 8 + (x)*12)
#define NOTE_A(x) ( 9 + (x)*12)
#define NOTE_A_SHARP(x) (10 + (x)*12)
#define NOTE_B_FLAT(x) (10 + (x)*12)
#define NOTE_B(x) (11 + (x)*12)
/*! \brief silences buzzer for the note duration */
#define SILENT_NOTE 0xFF
/*! \brief frequency bit that indicates Hz/10
* e.g. \a frequency = `(445 | DIV_BY_10)` gives a frequency of 44.5 Hz
*/
#define DIV_BY_10 (1 << 15)
/*! @} */
class ZumoBuzzer
{
public:
// constructor
ZumoBuzzer();
/*! \brief Plays the specified frequency for the specified duration.
*
* \param freq Frequency to play in Hz (or 0.1 Hz if the `DIV_BY_10` bit
* is set).
* \param duration Duration of the note in milliseconds.
* \param volume Volume of the note (0--15).
*
* The \a frequency argument must be between 40 Hz and 10 kHz. If the most
* significant bit of \a frequency is set, the frequency played is the value
* of the lower 15 bits of \a frequency in units of 0.1 Hz. Therefore, you can
* play a frequency of 44.5 Hz by using a \a frequency of `(DIV_BY_10 | 445)`.
* If the most significant bit of \a frequency is not set, the units for
* frequency are Hz. The \a volume argument controls the buzzer volume, with
* 15 being the loudest and 0 being the quietest. A \a volume of 15 supplies
* the buzzer with a 50% duty cycle PWM at the specified \a frequency.
* Lowering \a 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 ###
*
* ~~~{.ino}
* ZumoBuzzer 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 \a frequency × \a duration / 1000 must be no greater than
0xFFFF (65535). This means you can't use a max 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.
*/
static void playFrequency(unsigned int freq, unsigned int duration,
unsigned char volume);
/*! \brief Plays the specified note for the specified duration.
*
* \param note Note to play (see \ref note_macros "Note Macros").
* \param duration Duration of the note in milliseconds.
* \param volume Volume of the note (0--15).
*
* The \a note argument is an enumeration for the notes of the equal tempered
* scale (ETS). See \ref note_macros "Note Macros" for more information. The
* \a volume argument controls the buzzer volume, with 15 being the loudest
* and 0 being the quietest. A \a volume of 15 supplies the buzzer with a 50%
* duty cycle PWM at the specified \a frequency. Lowering \a 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.
*/
static void playNote(unsigned char note, unsigned int duration,
unsigned char volume);
/*! \brief Plays the specified sequence of notes.
*
* \param 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. |