PX4 Firmware
PX4 Autopilot Software http://px4.io
tunes.h
Go to the documentation of this file.
1 /****************************************************************************
2  *
3  * Copyright (c) 2017 PX4 Development Team. All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * 1. Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in
13  * the documentation and/or other materials provided with the
14  * distribution.
15  * 3. Neither the name PX4 nor the names of its contributors may be
16  * used to endorse or promote products derived from this software
17  * without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
23  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
25  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
26  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
29  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30  * POSSIBILITY OF SUCH DAMAGE.
31  *
32  ****************************************************************************/
33 
34 /**
35  * @file tunes.h
36  */
37 
38 #pragma once
39 
40 #include <uORB/uORB.h>
42 #include "tune_definition.h"
43 
44 #define TUNE_DEFAULT_NOTE_LENGTH 4
45 #define TUNE_DEFAULT_OCTAVE 4
46 #define TUNE_DEFAULT_TEMPO 120
47 
48 #define TUNE_MAX_UPDATE_INTERVAL_US 100000
49 
50 
51 /**
52  * Library for parsing tunes from melody-strings or dedicated tune messages.
53  * Needs to be instantiated as it keeps track of which tune is to be played
54  * next. Also handles repeated tunes.
55  */
56 class Tunes
57 {
58 public:
59  enum class NoteMode {NORMAL, LEGATO, STACCATO};
60 
61  /**
62  * Constructor with the default parameters set to:
63  * default_tempo: TUNE_DEFAULT_TEMPO
64  * default_octave: TUNE_DEFAULT_OCTAVE
65  * default_note_length: TUNE_DEFAULT_NOTE_LENGTH
66  * default_mode: NORMAL
67  */
68  Tunes(unsigned default_note_length = TUNE_DEFAULT_NOTE_LENGTH,
69  NoteMode default_note_mode = NoteMode::NORMAL,
70  unsigned default_octave = TUNE_DEFAULT_OCTAVE,
71  unsigned default_tempo = TUNE_DEFAULT_TEMPO);
72 
73  ~Tunes() = default;
74 
75  /**
76  * Set tune to be played using the message. If a tune is already being played
77  * the call to this function will be ignored, unless the override flag is set
78  * or the tune being already played is a repeated tune.
79  * @param tune_control struct containig the uORB message
80  * @return return -EINVAL if the default tune does not exist.
81  */
83 
84  /**
85  * Set tune to be played using a string.
86  * Parses a tune string, formatted with the syntax of the Microsoft GWBasic/QBasic.
87  * Ownership of the string is NOT transferred. The string has to be kept in
88  * memory for the whole duration of the melody.
89  *
90  * @param string tune input string
91  */
92  void set_string(const char *const string, uint8_t volume);
93 
94  /**
95  * Get next note in the current tune, which has been provided by either
96  * set_control or play_string
97  * @param frequency return frequency value (Hz)
98  * @param duration return duration of the tone (us)
99  * @param silence return silence duration (us)
100  * @return -1 for error, 0 for play one tone and 1 for continue a sequence
101  */
102  int get_next_note(unsigned &frequency, unsigned &duration, unsigned &silence);
103 
104  /**
105  * Get next note in the current tune, which has been provided by either
106  * set_control or play_string
107  * @param frequency return frequency value (Hz)
108  * @param duration return duration of the note (us)
109  * @param silence return silence duration (us)
110  * @param volume return the volume level of the note (between 0-100)
111  * @return -1 for no tune available/error, 0 to not play anything and 1 to play
112  */
113  int get_next_note(unsigned &frequency, unsigned &duration,
114  unsigned &silence, uint8_t &volume);
115 
116  /**
117  * Get the number of default tunes. This is useful for when a tune is
118  * requested via its tune ID.
119  * @return Number of default tunes accessible via tune ID
120  */
121  unsigned int get_default_tunes_size() const {return _default_tunes_size;}
122 
123  unsigned int get_maximum_update_interval() {return (unsigned int)TUNE_MAX_UPDATE_INTERVAL_US;}
124 
125 private:
126 
127  /**
128  * Convert note to frequency
129  *
130  * @param note unsigned value of the semitone from C
131  * @return frequency (Hz)
132  */
133  uint32_t note_to_frequency(unsigned note) const;
134 
135  /**
136  * Calculate the duration in microseconds of play and silence for a
137  * note given the current tempo, length and mode and the number of
138  * dots following in the play string.
139  *
140  * @param silence return silence duration (us)
141  * @param note_length note length
142  * @param dots extention of the note length
143  * @return duration of the note (us)
144  */
145  unsigned note_duration(unsigned &silence, unsigned note_length, unsigned dots) const;
146 
147  /**
148  * Calculate the duration in microseconds of a rest corresponding to
149  * a given note length.
150  *
151  * @param rest_length rest lenght in fraction of a note
152  * @param dots number of extension dots
153  * @return rest duration (us)
154  */
155  unsigned rest_duration(unsigned rest_length, unsigned dots) const;
156 
157  /**
158  * Find the next character in the string, discard any whitespace.
159  *
160  * @return uppercase version of the char.
161  */
162  int next_char();
163 
164  /**
165  * Extract a number from the string, consuming all the digit characters.
166  *
167  * @return extracted number.
168  */
169  unsigned next_number();
170 
171  /**
172  * Consume dot characters from the string
173  *
174  * @return number of consumed dots
175  */
176  unsigned next_dots();
177 
178  /**
179  * Reset the tune parameters. This is necessary when for example a tune moved
180  * one or more octaves up or down. reset() should always be called before
181  * (re)-starting a tune.
182  */
183  void reset(bool repeat_flag);
184 
185  int tune_end();
186 
187  int tune_error();
188 
189  static const char *const _default_tunes[];
190  static const bool _default_tunes_interruptable[];
191  static const unsigned int _default_tunes_size;
192  static const uint8_t _note_tab[];
193 
194  const char *_next_tune = nullptr; ///< next note in the string
195  const char *_tune = nullptr; ///< current tune string
196  const char *_tune_start_ptr = nullptr; ///< pointer to repeat tune
197 
198  int _current_tune_id = static_cast<int>(TuneID::NONE);
199 
200  bool _repeat = false; ///< if true, tune restarts at end
201 
206 
209  unsigned int _octave = TUNE_DEFAULT_OCTAVE;
210  unsigned int _tempo = TUNE_DEFAULT_TEMPO;
211 
212  unsigned int _duration = 0;
213  unsigned int _frequency = 0;
214  unsigned int _silence = 0;
215  uint8_t _volume = 0;
216 
217  bool _using_custom_msg = false;
218 };
#define TUNE_DEFAULT_NOTE_LENGTH
Definition: tunes.h:44
Tunes(unsigned default_note_length=TUNE_DEFAULT_NOTE_LENGTH, NoteMode default_note_mode=NoteMode::NORMAL, unsigned default_octave=TUNE_DEFAULT_OCTAVE, unsigned default_tempo=TUNE_DEFAULT_TEMPO)
Constructor with the default parameters set to: default_tempo: TUNE_DEFAULT_TEMPO default_octave: TUN...
Definition: tunes.cpp:56
int get_next_note(unsigned &frequency, unsigned &duration, unsigned &silence)
Get next note in the current tune, which has been provided by either set_control or play_string...
Definition: tunes.cpp:172
int next_char()
Find the next character in the string, discard any whitespace.
Definition: tunes.cpp:441
API for the uORB lightweight object broker.
Driver for the PX4 audio .
NoteMode _note_mode
Definition: tunes.h:208
unsigned int _silence
Definition: tunes.h:214
static const uint8_t _note_tab[]
Definition: tunes.h:192
unsigned int _default_tempo
Definition: tunes.h:205
NoteMode
Definition: tunes.h:59
unsigned int _frequency
Definition: tunes.h:213
unsigned note_duration(unsigned &silence, unsigned note_length, unsigned dots) const
Calculate the duration in microseconds of play and silence for a note given the current tempo...
Definition: tunes.cpp:384
unsigned next_dots()
Consume dot characters from the string.
Definition: tunes.cpp:467
bool _using_custom_msg
Definition: tunes.h:217
Library for parsing tunes from melody-strings or dedicated tune messages.
Definition: tunes.h:56
static const bool _default_tunes_interruptable[]
Definition: tunes.h:190
#define TUNE_DEFAULT_OCTAVE
Definition: tunes.h:45
const char * _tune_start_ptr
pointer to repeat tune
Definition: tunes.h:196
unsigned int _tempo
Definition: tunes.h:210
uint8_t _volume
Definition: tunes.h:215
void reset(bool repeat_flag)
Reset the tune parameters.
Definition: tunes.cpp:66
int set_control(const tune_control_s &tune_control)
Set tune to be played using the message.
Definition: tunes.cpp:85
static const char *const _default_tunes[]
Definition: tunes.h:189
unsigned next_number()
Extract a number from the string, consuming all the digit characters.
Definition: tunes.cpp:450
const char * _tune
current tune string
Definition: tunes.h:195
NoteMode _default_note_mode
Definition: tunes.h:203
uint32_t note_to_frequency(unsigned note) const
Convert note to frequency.
Definition: tunes.cpp:378
int tune_end()
Definition: tunes.cpp:356
unsigned int _default_octave
Definition: tunes.h:204
unsigned int _note_length
Definition: tunes.h:207
int _current_tune_id
Definition: tunes.h:198
#define TUNE_MAX_UPDATE_INTERVAL_US
Definition: tunes.h:48
#define TUNE_DEFAULT_TEMPO
Definition: tunes.h:46
unsigned int _default_note_length
Definition: tunes.h:202
~Tunes()=default
const char * _next_tune
next note in the string
Definition: tunes.h:194
int tune_error()
Definition: tunes.cpp:370
static tune_control_s tune_control
static const unsigned int _default_tunes_size
Definition: tunes.h:191
unsigned int _duration
Definition: tunes.h:212
unsigned rest_duration(unsigned rest_length, unsigned dots) const
Calculate the duration in microseconds of a rest corresponding to a given note length.
Definition: tunes.cpp:421
unsigned int get_default_tunes_size() const
Get the number of default tunes.
Definition: tunes.h:121
void set_string(const char *const string, uint8_t volume)
Set tune to be played using a string.
Definition: tunes.cpp:138
bool _repeat
if true, tune restarts at end
Definition: tunes.h:200
unsigned int get_maximum_update_interval()
Definition: tunes.h:123
unsigned int _octave
Definition: tunes.h:209