[232] | 1 | /*! \file ZumoBuzzer.h
|
---|
| 2 | *
|
---|
| 3 | * See the ZumoBuzzer class reference for more information about this library.
|
---|
| 4 | *
|
---|
| 5 | * \class ZumoBuzzer ZumoBuzzer.h
|
---|
| 6 | * \brief Play beeps and music with buzzer
|
---|
| 7 | *
|
---|
| 8 | * The ZumoBuzzer library allows various sounds to be played through the buzzer
|
---|
| 9 | * on the Zumo Shield, from simple beeps to complex tunes. The buzzer is
|
---|
| 10 | * controlled using a PWM output of Timer 2 (on the Arduino Uno and other
|
---|
| 11 | * ATmega328/168 boards) or Timer 4 (on the Arduino Leonardo and other
|
---|
| 12 | * ATmega32U4 boards), so it will conflict with any other uses of that timer.
|
---|
| 13 | *
|
---|
| 14 | * Note durations are timed using a timer overflow interrupt
|
---|
| 15 | * (`TIMER2_OVF`/`TIMER4_OVF`), which will briefly interrupt execution of your
|
---|
| 16 | * main program at the frequency of the sound being played. In most cases, the
|
---|
| 17 | * interrupt-handling routine is very short (several microseconds). However,
|
---|
| 18 | * when playing a sequence of notes in `PLAY_AUTOMATIC` mode (the default mode)
|
---|
| 19 | * with the `play()` command, this interrupt takes much longer than normal
|
---|
| 20 | * (perhaps several hundred microseconds) every time it starts a new note. It is
|
---|
| 21 | * important to take this into account when writing timing-critical code.
|
---|
| 22 | *
|
---|
| 23 | * The ZumoBuzzer library is fully compatible with the OrangutanBuzzer functions
|
---|
| 24 | * in the [Pololu AVR C/C++ Library](http://www.pololu.com/docs/0J18), so any
|
---|
| 25 | * sequences and melodies written for OrangutanBuzzer functions will also work
|
---|
| 26 | * with the equivalent ZumoBuzzer functions.
|
---|
| 27 | */
|
---|
| 28 |
|
---|
| 29 | #ifndef ZumoBuzzer_h
|
---|
| 30 | #define ZumoBuzzer_h
|
---|
| 31 |
|
---|
| 32 | #define PLAY_AUTOMATIC 0
|
---|
| 33 | #define PLAY_CHECK 1
|
---|
| 34 |
|
---|
| 35 | // n
|
---|
| 36 | // Equal Tempered Scale is given by f = f * a
|
---|
| 37 | // n o
|
---|
| 38 | //
|
---|
| 39 | // where f is chosen as A above middle C (A4) at f = 440 Hz
|
---|
| 40 | // o o
|
---|
| 41 | // and a is given by the twelfth root of 2 (~1.059463094359)
|
---|
| 42 |
|
---|
| 43 | /*! \anchor note_macros
|
---|
| 44 | *
|
---|
| 45 | * \name Note Macros
|
---|
| 46 | * \a x specifies the octave of the note
|
---|
| 47 | * @{
|
---|
| 48 | */
|
---|
| 49 | #define NOTE_C(x) ( 0 + (x)*12)
|
---|
| 50 | #define NOTE_C_SHARP(x) ( 1 + (x)*12)
|
---|
| 51 | #define NOTE_D_FLAT(x) ( 1 + (x)*12)
|
---|
| 52 | #define NOTE_D(x) ( 2 + (x)*12)
|
---|
| 53 | #define NOTE_D_SHARP(x) ( 3 + (x)*12)
|
---|
| 54 | #define NOTE_E_FLAT(x) ( 3 + (x)*12)
|
---|
| 55 | #define NOTE_E(x) ( 4 + (x)*12)
|
---|
| 56 | #define NOTE_F(x) ( 5 + (x)*12)
|
---|
| 57 | #define NOTE_F_SHARP(x) ( 6 + (x)*12)
|
---|
| 58 | #define NOTE_G_FLAT(x) ( 6 + (x)*12)
|
---|
| 59 | #define NOTE_G(x) ( 7 + (x)*12)
|
---|
| 60 | #define NOTE_G_SHARP(x) ( 8 + (x)*12)
|
---|
| 61 | #define NOTE_A_FLAT(x) ( 8 + (x)*12)
|
---|
| 62 | #define NOTE_A(x) ( 9 + (x)*12)
|
---|
| 63 | #define NOTE_A_SHARP(x) (10 + (x)*12)
|
---|
| 64 | #define NOTE_B_FLAT(x) (10 + (x)*12)
|
---|
| 65 | #define NOTE_B(x) (11 + (x)*12)
|
---|
| 66 |
|
---|
| 67 | /*! \brief silences buzzer for the note duration */
|
---|
| 68 | #define SILENT_NOTE 0xFF
|
---|
| 69 |
|
---|
| 70 | /*! \brief frequency bit that indicates Hz/10<br>
|
---|
| 71 | * e.g. \a frequency = `(445 | DIV_BY_10)` gives a frequency of 44.5 Hz
|
---|
| 72 | */
|
---|
| 73 | #define DIV_BY_10 (1 << 15)
|
---|
| 74 | /*! @} */
|
---|
| 75 |
|
---|
| 76 | class ZumoBuzzer
|
---|
| 77 | {
|
---|
| 78 | public:
|
---|
| 79 |
|
---|
| 80 | // constructor
|
---|
| 81 | ZumoBuzzer();
|
---|
| 82 |
|
---|
| 83 | /*! \brief Plays the specified frequency for the specified duration.
|
---|
| 84 | *
|
---|
| 85 | * \param freq Frequency to play in Hz (or 0.1 Hz if the `DIV_BY_10` bit
|
---|
| 86 | * is set).
|
---|
| 87 | * \param duration Duration of the note in milliseconds.
|
---|
| 88 | * \param volume Volume of the note (0--15).
|
---|
| 89 | *
|
---|
| 90 | * The \a frequency argument must be between 40 Hz and 10 kHz. If the most
|
---|
| 91 | * significant bit of \a frequency is set, the frequency played is the value
|
---|
| 92 | * of the lower 15 bits of \a frequency in units of 0.1 Hz. Therefore, you can
|
---|
| 93 | * play a frequency of 44.5 Hz by using a \a frequency of `(DIV_BY_10 | 445)`.
|
---|
| 94 | * If the most significant bit of \a frequency is not set, the units for
|
---|
| 95 | * frequency are Hz. The \a volume argument controls the buzzer volume, with
|
---|
| 96 | * 15 being the loudest and 0 being the quietest. A \a volume of 15 supplies
|
---|
| 97 | * the buzzer with a 50% duty cycle PWM at the specified \a frequency.
|
---|
| 98 | * Lowering \a volume by one halves the duty cycle (so 14 gives a 25% duty
|
---|
| 99 | * cycle, 13 gives a 12.5% duty cycle, etc). The volume control is somewhat
|
---|
| 100 | * crude (especially on the ATmega328/168) and should be thought of as a bonus
|
---|
| 101 | * feature.
|
---|
| 102 | *
|
---|
| 103 | * This function plays the note in the background while your program continues
|
---|
| 104 | * to execute. If you call another buzzer function while the note is playing,
|
---|
| 105 | * the new function call will overwrite the previous and take control of the
|
---|
| 106 | * buzzer. If you want to string notes together, you should either use the
|
---|
| 107 | * `play()` function or put an appropriate delay after you start a note
|
---|
| 108 | * playing. You can use the `is_playing()` function to figure out when the
|
---|
| 109 | * buzzer is through playing its note or melody.
|
---|
| 110 | *
|
---|
| 111 | * ### Example ###
|
---|
| 112 | *
|
---|
| 113 | * ~~~{.ino}
|
---|
| 114 | * ZumoBuzzer buzzer;
|
---|
| 115 | *
|
---|
| 116 | * ...
|
---|
| 117 | *
|
---|
| 118 | * // play a 6 kHz note for 250 ms at a lower volume
|
---|
| 119 | * buzzer.playFrequency(6000, 250, 12);
|
---|
| 120 | *
|
---|
| 121 | * // wait for buzzer to finish playing the note
|
---|
| 122 | * while (buzzer.isPlaying());
|
---|
| 123 | *
|
---|
| 124 | * // play a 44.5 Hz note for 1 s at full volume
|
---|
| 125 | * buzzer.playFrequency(DIV_BY_10 | 445, 1000, 15);
|
---|
| 126 | * ~~~
|
---|
| 127 | *
|
---|
| 128 | * \warning \a frequency × \a duration / 1000 must be no greater than
|
---|
| 129 | 0xFFFF (65535). This means you can't use a max duration of 65535 ms for
|
---|
| 130 | frequencies greater than 1 kHz. For example, the maximum duration you can
|
---|
| 131 | use for a frequency of 10 kHz is 6553 ms. If you use a duration longer than
|
---|
| 132 | this, you will produce an integer overflow that can result in unexpected
|
---|
| 133 | behavior.
|
---|
| 134 | */
|
---|
| 135 | static void playFrequency(unsigned int freq, unsigned int duration,
|
---|
| 136 | unsigned char volume);
|
---|
| 137 |
|
---|
| 138 | /*! \brief Plays the specified note for the specified duration.
|
---|
| 139 | *
|
---|
| 140 | * \param note Note to play (see \ref note_macros "Note Macros").
|
---|
| 141 | * \param duration Duration of the note in milliseconds.
|
---|
| 142 | * \param volume Volume of the note (0--15).
|
---|
| 143 | *
|
---|
| 144 | * The \a note argument is an enumeration for the notes of the equal tempered
|
---|
| 145 | * scale (ETS). See \ref note_macros "Note Macros" for more information. The
|
---|
| 146 | * \a volume argument controls the buzzer volume, with 15 being the loudest
|
---|
| 147 | * and 0 being the quietest. A \a volume of 15 supplies the buzzer with a 50%
|
---|
| 148 | * duty cycle PWM at the specified \a frequency. Lowering \a volume by one
|
---|
| 149 | * halves the duty cycle (so 14 gives a 25% duty cycle, 13 gives a 12.5% duty
|
---|
| 150 | * cycle, etc). The volume control is somewhat crude (especially on the
|
---|
| 151 | * ATmega328/168) and should be thought of as a bonus feature.
|
---|
| 152 | *
|
---|
| 153 | * This function plays the note in the background while your program continues
|
---|
| 154 | * to execute. If you call another buzzer function while the note is playing,
|
---|
| 155 | * the new function call will overwrite the previous and take control of the
|
---|
| 156 | * buzzer. If you want to string notes together, you should either use the
|
---|
| 157 | * `play()` function or put an appropriate delay after you start a note
|
---|
| 158 | * playing. You can use the `is_playing()` function to figure out when the
|
---|
| 159 | * buzzer is through playing its note or melody.
|
---|
| 160 | */
|
---|
| 161 | static void playNote(unsigned char note, unsigned int duration,
|
---|
| 162 | unsigned char volume);
|
---|
| 163 |
|
---|
| 164 | /*! \brief Plays the specified sequence of notes.
|
---|
| 165 | *
|
---|
| 166 | * \param sequence Char array containing a sequence of notes to play.
|
---|
| 167 | *
|
---|
| 168 | * If the play mode is `PLAY_AUTOMATIC` (default), the sequence of notes will
|
---|
| 169 | * play with no further action required by the user. If the play mode is
|
---|
| 170 | * `PLAY_CHECK`, the user will need to call `playCheck()` in the main loop to
|
---|
| 171 | * initiate the playing of each new note in the sequence. The play mode can be
|
---|
| 172 | * changed while the sequence is playing. The sequence syntax is modeled after
|
---|
| 173 | * the PLAY commands in GW-BASIC, with just a few differences.
|
---|
| 174 | *
|
---|
| 175 | * The notes are specified by the characters **C**, **D**, **E**, **F**,
|
---|
| 176 | * **G**, **A**, and **B**, and they are played by default as "quarter notes"
|
---|
| 177 | * with a length of 500 ms. This corresponds to a tempo of 120 beats/min.
|
---|
| 178 | * Other durations can be specified by putting a number immediately after the
|
---|
| 179 | * note. For example, C8 specifies C played as an eighth note, with half the
|
---|
| 180 | * duration of a quarter note. The special note **R** plays a rest (no sound).
|
---|
| 181 | * The sequence parser is case-insensitive and ignores spaces, which may be
|
---|
| 182 | * used to format your music nicely.
|
---|
| 183 | *
|
---|
| 184 | * Various control characters alter the sound:
|
---|
| 185 | * <table>
|
---|
| 186 | * <tr><th>Control character(s)</th><th>Effect</th></tr>
|
---|
| 187 | * <tr><td><strong>A--G</strong></td>
|
---|
| 188 | * <td>Specifies a note that will be played.</td></tr>
|
---|
| 189 | * <tr><td><strong>R</strong></td>
|
---|
| 190 | * <td>Specifies a rest (no sound for the duration of the note).</td></tr>
|
---|
| 191 | * <tr><td><strong>+</strong></strong> or <strong>#</strong> after a note</td>
|
---|
| 192 | * <td>Raises the preceding note one half-step.</td></tr>
|
---|
| 193 | * <tr><td><strong>-</strong> after a note</td>
|
---|
| 194 | * <td>Lowers the preceding note one half-step.</td></tr>
|
---|
| 195 | * <tr><td><strong>1--2000</strong> after a note</td>
|
---|
| 196 | * <td>Determines the duration of the preceding note. For example, C16
|
---|
| 197 | * specifies C played as a sixteenth note (1/16th the length of a
|
---|
| 198 | * whole note).</td></tr>
|
---|
| 199 | * <tr><td><strong>.</strong> after a note</td>
|
---|
| 200 | * <td>"Dots" the preceding note, increasing the length by 50%. Each
|
---|
| 201 | * additional dot adds half as much as the previous dot, so that "A.."
|
---|
| 202 | * is 1.75 times the length of "A".</td></tr>
|
---|
| 203 | * <tr><td><strong>></strong> before a note</td>
|
---|
| 204 | * <td>Plays the following note one octave higher.</td></tr>
|
---|
| 205 | * <tr><td><strong><</strong> before a note</td>
|
---|
| 206 | * <td>Plays the following note one octave lower.</td></tr>
|
---|
| 207 | * <tr><td><strong>O</strong> followed by a number</td>
|
---|
| 208 | * <td>Sets the octave. (default: **O4**)</td></tr>
|
---|
| 209 | * <tr><td><strong>T</strong> followed by a number</td>
|
---|
| 210 | * <td>Sets the tempo in beats per minute (BPM). (default: **T120**)</td></tr>
|
---|
| 211 | * <tr><td><strong>L</strong> followed by a number</td>
|
---|
| 212 | * <td>Sets the default note duration to the type specified by the number:
|
---|
| 213 | * 4 for quarter notes, 8 for eighth notes, 16 for sixteenth notes,
|
---|
| 214 | * etc. (default: **L4**)</td></tr>
|
---|
| 215 | * <tr><td><strong>V</strong> followed by a number</td>
|
---|
| 216 | * <td>Sets the music volume (0--15). (default: **V15**)</td></tr>
|
---|
| 217 | * <tr><td><strong>MS</strong></td>
|
---|
| 218 | * <td>Sets all subsequent notes to play play staccato -- each note is
|
---|
| 219 | * played for 1/2 of its allotted time, followed by an equal period of
|
---|
| 220 | * silence.</td></tr>
|
---|
| 221 | * <tr><td><strong>ML</strong></td>
|
---|
| 222 | * <td>Sets all subsequent notes to play legato -- each note is played for
|
---|
| 223 | * full length. This is the default setting.</td></tr>
|
---|
| 224 | * <tr><td><strong>!</strong></td>
|
---|
| 225 | * <td>Resets the octave, tempo, duration, volume, and staccato setting to
|
---|
| 226 | * their default values. These settings persist from one `play()` to the
|
---|
| 227 | * next, which allows you to more conveniently break up your music into
|
---|
| 228 | * reusable sections.</td></tr>
|
---|
| 229 | * </table>
|
---|
| 230 | *
|
---|
| 231 | * This function plays the string of notes in the background while your
|
---|
| 232 | * program continues to execute. If you call another buzzer function while the
|
---|
| 233 | * melody is playing, the new function call will overwrite the previous and
|
---|
| 234 | * take control of the buzzer. If you want to string melodies together, you
|
---|
| 235 | * should put an appropriate delay after you start a melody playing. You can
|
---|
| 236 | * use the `is_playing()` function to figure out when the buzzer is through
|
---|
| 237 | * playing the melody.
|
---|
| 238 | *
|
---|
| 239 | * ### Example ###
|
---|
| 240 | *
|
---|
| 241 | * ~~~{.ino}
|
---|
| 242 | * ZumoBuzzer buzzer;
|
---|
| 243 | *
|
---|
| 244 | * ...
|
---|
| 245 | *
|
---|
| 246 | * // play a C major scale up and back down:
|
---|
| 247 | * buzzer.play("!L16 V8 cdefgab>cbagfedc");
|
---|
| 248 | * while (buzzer.isPlaying());
|
---|
| 249 | *
|
---|
| 250 | * // the first few measures of Bach's fugue in D-minor
|
---|
| 251 | * buzzer.play("!T240 L8 agafaea dac+adaea fa<aa<bac#a dac#adaea f4");
|
---|
| 252 | * ~~~
|
---|
| 253 | */
|
---|
| 254 | static void play(const char *sequence);
|
---|
| 255 |
|
---|
| 256 | /*! \brief Plays the specified sequence of notes from program space.
|
---|
| 257 | *
|
---|
| 258 | * \param sequence Char array in program space containing a sequence of notes
|
---|
| 259 | * to play.
|
---|
| 260 | *
|
---|
| 261 | * A version of `play()` that takes a pointer to program space instead of RAM.
|
---|
| 262 | * This is desirable since RAM is limited and the string must be in program
|
---|
| 263 | * space anyway.
|
---|
| 264 | *
|
---|
| 265 | * ### Example ###
|
---|
| 266 | *
|
---|
| 267 | * ~~~{.ino}
|
---|
| 268 | * #include <avr/pgmspace.h>
|
---|
| 269 | *
|
---|
| 270 | * ZumoBuzzer buzzer;
|
---|
| 271 | * const char melody[] PROGMEM = "!L16 V8 cdefgab>cbagfedc";
|
---|
| 272 | *
|
---|
| 273 | * ...
|
---|
| 274 | *
|
---|
| 275 | * buzzer.playFromProgramSpace(melody);
|
---|
| 276 | * ~~~
|
---|
| 277 | */
|
---|
| 278 | static void playFromProgramSpace(const char *sequence_p);
|
---|
| 279 |
|
---|
| 280 | /*! \brief Controls whether `play()` sequence is played automatically or
|
---|
| 281 | * must be driven with `playCheck()`.
|
---|
| 282 | *
|
---|
| 283 | * \param mode Play mode (either `PLAY_AUTOMATIC` or `PLAY_CHECK`).
|
---|
| 284 | *
|
---|
| 285 | * This method lets you determine whether the notes of the `play()` sequence
|
---|
| 286 | * are played automatically in the background or are driven by the
|
---|
| 287 | * `play_check()` method. If \a mode is `PLAY_AUTOMATIC`, the sequence will
|
---|
| 288 | * play automatically in the background, driven by the timer overflow
|
---|
| 289 | * interrupt. The interrupt will take a considerable amount of time to execute
|
---|
| 290 | * when it starts the next note in the sequence playing, so it is recommended
|
---|
| 291 | * that you do not use automatic-play if you cannot tolerate being interrupted
|
---|
| 292 | * for more than a few microseconds. If \a mode is `PLAY_CHECK`, you can
|
---|
| 293 | * control when the next note in the sequence is played by calling the
|
---|
| 294 | * `play_check()` method at acceptable points in your main loop. If your main
|
---|
| 295 | * loop has substantial delays, it is recommended that you use automatic-play
|
---|
| 296 | * mode rather than play-check mode. Note that the play mode can be changed
|
---|
| 297 | * while the sequence is being played. The mode is set to `PLAY_AUTOMATIC` by
|
---|
| 298 | * default.
|
---|
| 299 | */
|
---|
| 300 | static void playMode(unsigned char mode);
|
---|
| 301 |
|
---|
| 302 | /*! \brief Starts the next note in a sequence, if necessary, in `PLAY_CHECK`
|
---|
| 303 | * mode.
|
---|
| 304 | *
|
---|
| 305 | * \return 0 if sequence is complete, 1 otherwise.
|
---|
| 306 | *
|
---|
| 307 | * This method only needs to be called if you are in `PLAY_CHECK` mode. It
|
---|
| 308 | * checks to see whether it is time to start another note in the sequence
|
---|
| 309 | * initiated by `play()`, and starts it if so. If it is not yet time to start
|
---|
| 310 | * the next note, this method returns without doing anything. Call this as
|
---|
| 311 | * often as possible in your main loop to avoid delays between notes in the
|
---|
| 312 | * sequence. This method returns 0 (false) if the melody to be played is
|
---|
| 313 | * complete, otherwise it returns 1 (true).
|
---|
| 314 | */
|
---|
| 315 | static unsigned char playCheck();
|
---|
| 316 |
|
---|
| 317 | /*! \brief Checks whether a note, frequency, or sequence is being played.
|
---|
| 318 | *
|
---|
| 319 | * \return 1 if the buzzer is current playing a note, frequency, or sequence;
|
---|
| 320 | * 0 otherwise.
|
---|
| 321 | *
|
---|
| 322 | * This method returns 1 (true) if the buzzer is currently playing a
|
---|
| 323 | * note/frequency or if it is still playing a sequence started by `play()`.
|
---|
| 324 | * Otherwise, it returns 0 (false). You can poll this method to determine when
|
---|
| 325 | * it's time to play the next note in a sequence, or you can use it as the
|
---|
| 326 | * argument to a delay loop to wait while the buzzer is busy.
|
---|
| 327 | */
|
---|
| 328 | static unsigned char isPlaying();
|
---|
| 329 |
|
---|
| 330 | /*! \brief Stops any note, frequency, or melody being played.
|
---|
| 331 | *
|
---|
| 332 | * This method will immediately silence the buzzer and terminate any
|
---|
| 333 | * note/frequency/melody that is currently playing.
|
---|
| 334 | */
|
---|
| 335 | static void stopPlaying();
|
---|
| 336 |
|
---|
| 337 |
|
---|
| 338 | private:
|
---|
| 339 |
|
---|
| 340 | // initializes timer for buzzer control
|
---|
| 341 | static void init2();
|
---|
| 342 | static void init();
|
---|
| 343 | };
|
---|
| 344 |
|
---|
| 345 | #endif
|
---|