github/esphome
2
0
Fork 0
mirror of https://github.com/esphome/esphome.git synced 2026-09-14 00:28:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

[rtttl] improve comments Part 2 (#13971)

Browse Source 
Co-authored-by: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
This commit is contained in:
Thomas Rupprecht
2026-03-01 22:44:02 -05:00
committed by GitHub
co-authored by Jonathan Swoboda pre-commit-ci-lite[bot]
parent 0e18e4461e
commit 073ca63f60
2 changed files with 119 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files
esphome/components/rtttl/rtttl.cpp
+103 -86
View File
@@ -8,18 +8,26 @@ namespace esphome::rtttl {
static const char *const TAG = "rtttl";
// These values can also be found as constants in the Tone library (Tone.h)
static const uint16_t NOTES[] = {0, 262, 277, 294, 311, 330, 349, 370, 392, 415, 440, 466, 494,
523, 554, 587, 622, 659, 698, 740, 784, 831, 880, 932, 988, 1047,
1109, 1175, 1245, 1319, 1397, 1480, 1568, 1661, 1760, 1865, 1976, 2093, 2217,
2349, 2489, 2637, 2794, 2960, 3136, 3322, 3520, 3729, 3951};
static constexpr uint8_t SONG_NAME_LENGTH_LIMIT = 64;
static constexpr uint8_t SEMITONES_IN_OCTAVE = 12;
#if defined(USE_OUTPUT) || defined(USE_SPEAKER)
static const uint32_t DOUBLE_NOTE_GAP_MS = 10;
#endif // USE_OUTPUT || USE_SPEAKER
static constexpr uint8_t MIN_OCTAVE = 4;
static constexpr uint8_t MAX_OCTAVE = 7;
static constexpr uint8_t DEFAULT_BPM = 63; // Default beats per minute
// These values can also be found as constants in the Tone library (Tone.h)
static constexpr uint16_t NOTES[] = {0, 262, 277, 294, 311, 330, 349, 370, 392, 415, 440, 466, 494,
523, 554, 587, 622, 659, 698, 740, 784, 831, 880, 932, 988, 1047,
1109, 1175, 1245, 1319, 1397, 1480, 1568, 1661, 1760, 1865, 1976, 2093, 2217,
2349, 2489, 2637, 2794, 2960, 3136, 3322, 3520, 3729, 3951};
static constexpr uint8_t NOTES_COUNT = static_cast<uint8_t>(sizeof(NOTES) / sizeof(NOTES[0]));
static constexpr uint8_t REPEATING_NOTE_GAP_MS = 10;
#ifdef USE_SPEAKER
static const size_t SAMPLE_BUFFER_SIZE = 2048;
static constexpr uint16_t SAMPLE_BUFFER_SIZE = 2048;
static constexpr uint16_t SAMPLE_RATE = 16000;
struct SpeakerSample {
int8_t left{0};
@@ -27,7 +35,7 @@ struct SpeakerSample {
};
inline double deg2rad(double degrees) {
static const double PI_ON_180 = 4.0 * atan(1.0) / 180.0;
static constexpr double PI_ON_180 = M_PI / 180.0;
return degrees * PI_ON_180;
}
#endif // USE_SPEAKER
@@ -85,7 +93,7 @@ void Rtttl::loop() {
}
#ifdef USE_OUTPUT
if (this->output_ != nullptr && millis() - this->last_note_ < this->note_duration_) {
if (this->output_ != nullptr && millis() - this->last_note_start_time_ < this->note_duration_) {
return;
}
#endif // USE_OUTPUT
@@ -113,36 +121,34 @@ void Rtttl::loop() {
}
if (this->samples_sent_ != this->samples_count_) {
SpeakerSample sample[SAMPLE_BUFFER_SIZE + 2];
int x = 0;
uint16_t sample_index = 0;
double rem = 0.0;
while (true) {
// Try and send out the remainder of the existing note, one per loop()
if (this->samples_per_wave_ != 0 && this->samples_sent_ >= this->samples_gap_) { // Play note//
// Try and send out the remainder of the existing note, one per `loop()`
if (this->samples_per_wave_ != 0 && this->samples_sent_ >= this->samples_gap_) { // Play note
rem = ((this->samples_sent_ << 10) % this->samples_per_wave_) * (360.0 / this->samples_per_wave_);
int16_t val = (127 * this->gain_) * sin(deg2rad(rem)); // 16bit = 49152
sample[x].left = val;
sample[x].right = val;
int8_t val = (127 * this->gain_) * sin(deg2rad(rem));
sample[sample_index].left = val;
sample[sample_index].right = val;
} else {
sample[x].left = 0;
sample[x].right = 0;
sample[sample_index].left = 0;
sample[sample_index].right = 0;
}
if (static_cast<size_t>(x) >= SAMPLE_BUFFER_SIZE || this->samples_sent_ >= this->samples_count_) {
if (sample_index >= SAMPLE_BUFFER_SIZE || this->samples_sent_ >= this->samples_count_) {
break;
}
this->samples_sent_++;
x++;
sample_index++;
}
if (x > 0) {
size_t bytes_to_send = x * sizeof(SpeakerSample);
if (sample_index > 0) {
size_t bytes_to_send = sample_index * sizeof(SpeakerSample);
size_t send = this->speaker_->play((uint8_t *) (&sample), bytes_to_send);
if (send != bytes_to_send) {
this->samples_sent_ -= (x - (send / sizeof(SpeakerSample)));
this->samples_sent_ -= (sample_index - (send / sizeof(SpeakerSample)));
}
return;
}
@@ -155,83 +161,84 @@ void Rtttl::loop() {
return;
}
// align to note: most rtttl's out there does not add and space after the ',' separator but just in case...
// Align to note: most rtttl's out there does not add any space after the ',' separator but just in case
while (this->rtttl_[this->position_] == ',' || this->rtttl_[this->position_] == ' ') {
this->position_++;
}
// first, get note duration, if available
uint8_t num = this->get_integer_();
// First, get note duration, if available
uint8_t note_denominator = this->get_integer_();
if (num) {
this->note_duration_ = this->wholenote_ / num;
if (note_denominator) {
this->note_duration_ = this->wholenote_duration_ / note_denominator;
} else {
this->note_duration_ =
this->wholenote_ / this->default_duration_; // we will need to check if we are a dotted note after
// We will need to check if we are a dotted note after
this->note_duration_ = this->wholenote_duration_ / this->default_note_denominator_;
}
uint8_t note = note_index_from_char(this->rtttl_[this->position_]);
uint8_t note_index_in_octave = note_index_from_char(this->rtttl_[this->position_]);
this->position_++;
// now, get optional '#' sharp
// Now, get optional '#' sharp
if (this->rtttl_[this->position_] == '#') {
note++;
note_index_in_octave++;
this->position_++;
}
// now, get scale
// Now, get scale
uint8_t scale = this->get_integer_();
if (scale == 0) {
scale = this->default_octave_;
}
if (scale < 4 || scale > 7) {
ESP_LOGE(TAG, "Octave must be between 4 and 7 (it is %d)", scale);
if (scale < MIN_OCTAVE || scale > MAX_OCTAVE) {
ESP_LOGE(TAG, "Octave must be between %d and %d (it is %d)", MIN_OCTAVE, MAX_OCTAVE, scale);
this->finish_();
return;
}
// now, get optional '.' dotted note
// Now, get optional '.' dotted note
if (this->rtttl_[this->position_] == '.') {
this->note_duration_ += this->note_duration_ / 2;
this->note_duration_ += this->note_duration_ / 2; // Duration +50%
this->position_++;
}
// Now play the note
bool need_note_gap = false;
if (note) {
auto note_index = (scale - 4) * 12 + note;
if (note_index < 0 || note_index >= (int) (sizeof(NOTES) / sizeof(NOTES[0]))) {
ESP_LOGE(TAG, "Note out of range (note: %d, scale: %d, index: %d, max: %d)", note, scale, note_index,
(int) (sizeof(NOTES) / sizeof(NOTES[0])));
// Now play the note
if (note_index_in_octave == 0) {
this->output_freq_ = 0;
ESP_LOGVV(TAG, "Waiting: %dms", this->note_duration_);
} else {
uint8_t note_index = (scale - MIN_OCTAVE) * SEMITONES_IN_OCTAVE + note_index_in_octave;
if (note_index >= NOTES_COUNT) {
ESP_LOGE(TAG, "Note out of range (note: %d, scale: %d, index: %d, max: %d)", note_index_in_octave, scale,
note_index, NOTES_COUNT);
this->finish_();
return;
}
auto freq = NOTES[note_index];
uint16_t freq = NOTES[note_index];
need_note_gap = freq == this->output_freq_;
// Add small silence gap between same note
this->output_freq_ = freq;
ESP_LOGVV(TAG, "playing note: %d for %dms", note, this->note_duration_);
} else {
ESP_LOGVV(TAG, "waiting: %dms", this->note_duration_);
this->output_freq_ = 0;
ESP_LOGVV(TAG, "Playing note: %d for %dms", note_index_in_octave, this->note_duration_);
}
#ifdef USE_OUTPUT
if (this->output_ != nullptr) {
if (need_note_gap && this->note_duration_ > DOUBLE_NOTE_GAP_MS) {
if (this->output_freq_ == 0) {
this->output_->set_level(0.0);
delay(DOUBLE_NOTE_GAP_MS);
this->note_duration_ -= DOUBLE_NOTE_GAP_MS;
}
if (this->output_freq_ != 0) {
} else {
if (need_note_gap && this->note_duration_ > REPEATING_NOTE_GAP_MS) {
this->output_->set_level(0.0);
delay(REPEATING_NOTE_GAP_MS);
this->note_duration_ -= REPEATING_NOTE_GAP_MS;
}
this->output_->update_frequency(this->output_freq_);
this->output_->set_level(this->gain_);
} else {
this->output_->set_level(0.0);
}
}
#endif // USE_OUTPUT
@@ -241,28 +248,26 @@ void Rtttl::loop() {
this->samples_sent_ = 0;
this->samples_gap_ = 0;
this->samples_per_wave_ = 0;
this->samples_count_ = (this->sample_rate_ * this->note_duration_) / 1000;
this->samples_count_ = (SAMPLE_RATE * this->note_duration_) / 1000;
if (need_note_gap) {
this->samples_gap_ = (this->sample_rate_ * DOUBLE_NOTE_GAP_MS) / 1000;
this->samples_gap_ = (SAMPLE_RATE * REPEATING_NOTE_GAP_MS) / 1000;
}
if (this->output_freq_ != 0) {
// make sure there is enough samples to add a full last sinus.
uint16_t samples_wish = this->samples_count_;
this->samples_per_wave_ = (this->sample_rate_ << 10) / this->output_freq_;
// Make sure there is enough samples to add a full last sinus.
uint32_t samples_wish = this->samples_count_;
this->samples_per_wave_ = (SAMPLE_RATE << 10) / this->output_freq_;
uint16_t division = ((this->samples_count_ << 10) / this->samples_per_wave_) + 1;
this->samples_count_ = (division * this->samples_per_wave_);
this->samples_count_ = this->samples_count_ >> 10;
ESP_LOGVV(TAG, "- Calc play time: wish: %d gets: %d (div: %d spw: %d)", samples_wish, this->samples_count_,
division, this->samples_per_wave_);
this->samples_count_ = (division * this->samples_per_wave_) >> 10;
ESP_LOGVV(TAG, "Calc play time: wish: %" PRIu32 " gets: %" PRIu32 " (div: %d spw: %" PRIu32 ")", samples_wish,
this->samples_count_, division, this->samples_per_wave_);
}
// Convert from frequency in Hz to high and low samples in fixed point
}
#endif // USE_SPEAKER
this->last_note_ = millis();
this->last_note_start_time_ = millis();
}
void Rtttl::play(std::string rtttl) {
@@ -275,25 +280,28 @@ void Rtttl::play(std::string rtttl) {
this->rtttl_ = std::move(rtttl);
this->default_duration_ = 4;
this->default_octave_ = 6;
this->default_note_denominator_ = DEFAULT_NOTE_DENOMINATOR;
this->default_octave_ = DEFAULT_OCTAVE;
this->note_duration_ = 0;
int bpm = 63;
uint16_t num;
uint16_t bpm = DEFAULT_BPM;
uint16_t num; // Used for: default note-denominator, default octave, BPM
// Get name
this->position_ = this->rtttl_.find(':');
// it's somewhat documented to be up to 10 characters but let's be a bit flexible here
if (this->position_ == std::string::npos || this->position_ > 15) {
if (this->position_ == std::string::npos) {
ESP_LOGE(TAG, "Unable to determine name; missing ':'");
return;
}
if (this->position_ >= SONG_NAME_LENGTH_LIMIT) {
ESP_LOGE(TAG, "Name is too long: length=%u, limit=%u", static_cast<unsigned>(this->position_),
static_cast<unsigned>(SONG_NAME_LENGTH_LIMIT));
return;
}
ESP_LOGD(TAG, "Playing song %.*s", (int) this->position_, this->rtttl_.c_str());
// get default duration
// Get default duration
this->position_ = this->rtttl_.find("d=", this->position_);
if (this->position_ == std::string::npos) {
ESP_LOGE(TAG, "Missing 'd='");
@@ -301,11 +309,14 @@ void Rtttl::play(std::string rtttl) {
}
this->position_ += 2;
num = this->get_integer_();
if (num > 0) {
this->default_duration_ = num;
if (num == 1 || num == 2 || num == 4 || num == 8 || num == 16 || num == 32) {
this->default_note_denominator_ = num;
} else {
ESP_LOGE(TAG, "Invalid default duration: %d", num);
return;
}
// get default octave
// Get default octave
this->position_ = this->rtttl_.find("o=", this->position_);
if (this->position_ == std::string::npos) {
ESP_LOGE(TAG, "Missing 'o=");
@@ -313,11 +324,14 @@ void Rtttl::play(std::string rtttl) {
}
this->position_ += 2;
num = this->get_integer_();
if (num >= 3 && num <= 7) {
if (num >= MIN_OCTAVE && num <= MAX_OCTAVE) {
this->default_octave_ = num;
} else {
ESP_LOGE(TAG, "Invalid default octave: %d", num);
return;
}
// get BPM
// Get BPM
this->position_ = this->rtttl_.find("b=", this->position_);
if (this->position_ == std::string::npos) {
ESP_LOGE(TAG, "Missing b=");
@@ -325,8 +339,11 @@ void Rtttl::play(std::string rtttl) {
}
this->position_ += 2;
num = this->get_integer_();
if (num != 0) {
if (num >= 4) { // Below 4 is not realistic and would cause a integer overflow
bpm = num;
} else {
ESP_LOGE(TAG, "Invalid BPM: %d", num);
return;
}
this->position_ = this->rtttl_.find(':', this->position_);
@@ -337,10 +354,10 @@ void Rtttl::play(std::string rtttl) {
this->position_++;
// BPM usually expresses the number of quarter notes per minute
this->wholenote_ = 60 * 1000L * 4 / bpm; // this is the time for whole note (in milliseconds)
this->wholenote_duration_ = 60 * 1000L * 4 / bpm; // This is the time for whole note (in milliseconds)
this->output_freq_ = 0;
this->last_note_ = millis();
this->last_note_start_time_ = millis();
this->note_duration_ = 1;
#ifdef USE_OUTPUT
esphome/components/rtttl/rtttl.h
+16 -15
View File
@@ -13,6 +13,10 @@
namespace esphome::rtttl {
inline constexpr uint8_t DEFAULT_NOTE_DENOMINATOR = 4; // Default note-denominator (quarter note)
inline constexpr uint8_t DEFAULT_OCTAVE =
6; // Default octave for a note (see: `MIN_OCTAVE`, `MAX_OCTAVE` in `rtttl.cpp`)
enum class State : uint8_t {
STOPPED = 0,
INIT,
@@ -67,19 +71,18 @@ class Rtttl : public Component {
std::string rtttl_{""};
/// The current position in the RTTTL string.
size_t position_{0};
/// The duration of a whole note in milliseconds.
uint16_t wholenote_;
/// The default duration of a note (e.g. 4 for a quarter note).
uint16_t default_duration_;
uint8_t default_note_denominator_{DEFAULT_NOTE_DENOMINATOR};
/// The default octave for a note.
uint16_t default_octave_;
/// The time the last note was started.
uint32_t last_note_;
uint8_t default_octave_{DEFAULT_OCTAVE};
/// The duration of the current note in milliseconds.
uint16_t note_duration_;
uint16_t note_duration_{0};
/// The duration of a whole note in milliseconds.
uint16_t wholenote_duration_;
/// The time in milliseconds since microcontroller boot when the last note was started.
uint32_t last_note_start_time_;
/// The frequency of the current note in Hz.
uint32_t output_freq_;
uint32_t output_freq_{0};
/// The gain of the output.
float gain_{0.6f};
/// The current state of the RTTTL player.
@@ -93,16 +96,14 @@ class Rtttl : public Component {
#ifdef USE_SPEAKER
/// The speaker to write the sound to.
speaker::Speaker *speaker_{nullptr};
/// The sample rate of the speaker.
int sample_rate_{16000};
/// The number of samples for one full cycle of a note's waveform, in Q10 fixed-point format.
int samples_per_wave_{0};
uint32_t samples_per_wave_{0};
/// The number of samples sent.
int samples_sent_{0};
uint32_t samples_sent_{0};
/// The total number of samples to send.
int samples_count_{0};
uint32_t samples_count_{0};
/// The number of samples for the gap between notes.
int samples_gap_{0};
uint32_t samples_gap_{0};
#endif // USE_SPEAKER
/// The callback to call when playback is finished.