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
|
---|