diff --git a/Marlin/buzzer.h b/Marlin/buzzer.h index ec122d020ae6..e40b85474208 100644 --- a/Marlin/buzzer.h +++ b/Marlin/buzzer.h @@ -28,11 +28,19 @@ #define TONE_QUEUE_LENGTH 4 +/** + * @brief Tone structure + * @details Simple abstration of a tone based on a duration and a frequency. + * + */ struct tone_t { uint16_t duration; uint16_t frequency; }; +/** + * @brief Buzzer class + */ class Buzzer { private: struct state_t { @@ -43,34 +51,66 @@ class Buzzer { protected: CircularQueue buffer; + /** + * @brief Inverts the sate of a digital PIN + * @details This will invert the current state of an digital IO pin. + */ void invert() { WRITE(BEEPER_PIN, !READ(BEEPER_PIN)); } + /** + * @brief Turn off a digital PIN + * @details Alias of digitalWrite(PIN, LOW) using FastIO + */ void off() { WRITE(BEEPER_PIN, LOW); } + /** + * @brief Turn on a digital PIN + * @details Alias of digitalWrite(PIN, HIGH) using FastIO + */ void on() { WRITE(BEEPER_PIN, HIGH); } + /** + * @brief Resets the state of the class + * @details Brings the class state to a known one. + */ void reset() { this->off(); this->state.timestamp = 0; } public: + /** + * @brief Class constructor + */ Buzzer() { SET_OUTPUT(BEEPER_PIN); this->reset(); } + /** + * @brief Add a tone to the queue + * @details Adds a tone_t structure to the ring buffer, will block IO if the + * queue is full waiting for one slot to get available. + * + * @param duration Duration of the tone in milliseconds + * @param frequency Frequency of the tone in hertz + */ void tone(uint16_t const &duration, uint16_t const &frequency = 0) { while (buffer.isFull()) this->tick(); this->buffer.enqueue((tone_t) { duration, frequency }); } + /** + * @brief Loop function + * @details This function should be called at loop, it will take care of + * playing the tones in the queue. + */ virtual void tick() { if (!this->state.timestamp) { if (this->buffer.isEmpty()) return; diff --git a/Marlin/circularqueue.h b/Marlin/circularqueue.h index 99828616974c..99efd244efd3 100644 --- a/Marlin/circularqueue.h +++ b/Marlin/circularqueue.h @@ -25,10 +25,19 @@ #include +/** + * @brief Circular Queue class + * @details Implementation of the classic ring buffer data structure + */ template class CircularQueue { private: + /** + * @brief Buffer structure + * @details This structure consolidates all the overhead required to handle + * a circular queue such as the pointers and the buffer vector. + */ struct buffer_t { uint8_t head; uint8_t tail; @@ -38,11 +47,23 @@ class CircularQueue { } buffer; public: + /** + * @brief Class constructor + * @details This class requires two template parameters, T defines the type + * of the items this queue will handle and N defines the maximum number of + * items that can be stored on the queue. + */ CircularQueue() { this->buffer.length = N; this->buffer.size = this->buffer.head = this->buffer.tail = 0; } + /** + * @brief Removes and returns a item from the queue + * @details Removes the oldest item on the queue which is pointed by the + * buffer_t head variable, this item is then returned to the caller. + * @return type T item + */ T dequeue() { if (this->isEmpty()) return T(); @@ -55,6 +76,14 @@ class CircularQueue { return item; } + /** + * @brief Adds an item to the queue + * @details Adds a item to the queue on the location pointed by the buffer_t + * tail vairable, will return false if there is no queue space available. + * + * @param item Item to be added to the queue + * @return true if the operation was successfull + */ bool enqueue(T const &item) { if (this->isFull()) return false; @@ -67,22 +96,48 @@ class CircularQueue { return true; } + /** + * @brief Checks if the queue has no items + * @details Returns true if there are no items on the queue, false otherwise. + * @return true if queue is empty + */ bool isEmpty() { return this->buffer.size == 0; } + /** + * @brief Checks if the queue is full + * @details Returns true if the queue is full, false otherwise. + * @return true if queue is full + */ bool isFull() { return this->buffer.size == this->buffer.length; } + /** + * @brief Gets the queue size + * @details Returns the maximum number of items a queue can have. + * @return the queue lenght + */ uint8_t length() { return this->buffer.length; } + /** + * @brief Gets the next item from the queue without removing it + * @details Returns the next item on the queue but the item is not removed + * from the queue nor the pointers updated. + * @return the queue size + */ uint8_t peek() { return this->buffer.queue[this->buffer.head]; } + /** + * @brief Gets the number of items on the queue + * @details Returns the current number of items stored on the queue. + * @return type T item + */ uint8_t size() { return this->buffer.size; } diff --git a/Marlin/speaker.h b/Marlin/speaker.h index 24ede6c6dd78..93aa6f736187 100644 --- a/Marlin/speaker.h +++ b/Marlin/speaker.h @@ -36,6 +36,10 @@ class Speaker: public Buzzer { } state; protected: + /** + * @brief Resets the state of the class + * @details Brings the class state to a known one. + */ void reset() { super::reset(); this->state.period = 0; @@ -43,10 +47,18 @@ class Speaker: public Buzzer { } public: + /** + * @brief Class constructor + */ Speaker() { this->reset(); } + /** + * @brief Loop function + * @details This function should be called at loop, it will take care of + * playing the tones in the queue. + */ virtual void tick() { if (!this->state.cycles) { if (this->buffer.isEmpty()) return;