diff --git a/analog_input.h b/analog_input.h index 496899b..73f42c8 100644 --- a/analog_input.h +++ b/analog_input.h @@ -17,15 +17,18 @@ const int MAX_INPUT = (1 << 10) - 1; // Max 10 bit analog read resolution. const int CALIBRATED_LOW = -566; const int CALIBRATED_HIGH = 512; +/** + * @brief Class for interacting with analog inputs (CV). + */ class AnalogInput { public: AnalogInput() {} ~AnalogInput() {} /** - * Initializes a analog input object. + * @brief Initializes an analog input object. * - * @param pin gpio pin for the analog input. + * @param pin The GPIO pin for the analog input. */ void Init(uint8_t pin) { pinMode(pin, INPUT); @@ -33,8 +36,11 @@ class AnalogInput { } /** - * Read the value of the analog input and set instance state. + * @brief Reads and processes the analog input. * + * This method reads the raw value from the ADC, applies the current + * calibration, offset, and attenuation/inversion settings. It should be + * called regularly in the main loop to update the input's state. */ void Process() { old_read_ = read_; @@ -44,14 +50,38 @@ class AnalogInput { if (inverted_) read_ = -read_; } - // Set calibration values. - + /** + * @brief Adjusts the low calibration point. + * + * This is used to fine-tune the mapping of the raw analog input to the output range. + * + * @param amount The amount to add to the current low calibration value. + */ void AdjustCalibrationLow(int amount) { low_ += amount; } + /** + * @brief Adjusts the high calibration point. + * + * This is used to fine-tune the mapping of the raw analog input to the output range. + * + * @param amount The amount to add to the current high calibration value. + */ void AdjustCalibrationHigh(int amount) { high_ += amount; } + /** + * @brief Sets a DC offset for the input. + * + * @param percent A percentage (e.g., 0.5 for 50%) to shift the signal. + */ void SetOffset(float percent) { offset_ = -(percent)*512; } + /** + * @brief Sets the attenuation (scaling) of the input signal. + * + * This scales the input signal. A negative percentage will also invert the signal. + * + * @param percent The attenuation level, typically from 0.0 to 1.0. + */ void SetAttenuation(float percent) { low_ = abs(percent) * CALIBRATED_LOW; high_ = abs(percent) * CALIBRATED_HIGH; @@ -59,18 +89,16 @@ class AnalogInput { } /** - * Get the current value of the analog input within a range of +/-512. - * - * @return read value within a range of +/-512. + * @brief Get the current processed value of the analog input. * + * @return The read value within a range of +/-512. */ inline int16_t Read() { return read_; } /** - * Return the analog read value as voltage. - * - * @return A float representing the voltage (-5.0 to +5.0). + * @brief Return the analog read value as a voltage. * + * @return A float representing the calculated voltage (-5.0 to +5.0). */ inline float Voltage() { return ((read_ / 512.0) * 5.0); } @@ -85,4 +113,4 @@ class AnalogInput { bool inverted_ = false; }; -#endif +#endif \ No newline at end of file diff --git a/clock.h b/clock.h index 9cb2ad8..9b8ab5e 100644 --- a/clock.h +++ b/clock.h @@ -4,7 +4,7 @@ * @brief Wrapper Class for clock timing functions. * @version 0.1 * @date 2025-05-04 - * + * * @copyright MIT - (c) 2025 - Adam Wonak - adam.wonak@gmail.com * */ @@ -27,6 +27,9 @@ typedef void (*ExtCallback)(void); static ExtCallback extUserCallback = nullptr; static void serialEventNoop(uint8_t msg, uint8_t status) {} +/** + * @brief Wrapper Class for clock timing functions. + */ class Clock { public: static constexpr int DEFAULT_TEMPO = 120; @@ -47,6 +50,9 @@ class Clock { PULSE_LAST, }; + /** + * @brief Initializes the clock, MIDI serial, and sets default values. + */ void Init() { NeoSerial.begin(31250); @@ -67,18 +73,36 @@ class Clock { uClock.start(); } - // Handle external clock tick and call user callback when receiving clock trigger (PPQN_4, PPQN_24, or MIDI). + /** + * @brief Attach a handler for external clock ticks. + * + * This function attaches a user-defined callback to the external clock input pin interrupt. + * It is also called for incoming MIDI clock events. + * + * @param callback Function to call on an external clock event. + */ void AttachExtHandler(void (*callback)()) { extUserCallback = callback; attachInterrupt(digitalPinToInterrupt(EXT_PIN), callback, RISING); } - // Internal PPQN96 callback for all clock timer operations. + /** + * @brief Attach a handler for the internal high-resolution clock. + * + * Sets a callback function that is triggered at the internal PPQN_96 rate. This is the + * main internal timing callback for all clock operations. + * + * @param callback Function to call on every internal clock tick. It receives the tick count as a parameter. + */ void AttachIntHandler(void (*callback)(uint32_t)) { uClock.setOnOutputPPQN(callback); } - // Set the source of the clock mode. + /** + * @brief Set the source of the clock. + * + * @param source The new source for driving the clock. See the `Source` enum. + */ void SetSource(Source source) { bool was_playing = !IsPaused(); uClock.stop(); @@ -110,47 +134,81 @@ class Clock { } } - // Return true if the current selected source is externl (PPQN_4, PPQN_24, or MIDI). + /** + * @brief Checks if the clock source is external. + * + * @return true if the current source is external (PPQN_4, PPQN_24, or MIDI). + * @return false if the source is internal. + */ bool ExternalSource() { return uClock.getClockMode() == uClock.EXTERNAL_CLOCK; } - // Return true if the current selected source is the internal master clock. + /** + * @brief Checks if the clock source is internal. + * + * @return true if the current source is the internal master clock. + * @return false if the source is external. + */ bool InternalSource() { return uClock.getClockMode() == uClock.INTERNAL_CLOCK; } - // Returns the current BPM tempo. + /** + * @brief Gets the current tempo. + * + * @return int The current tempo in beats per minute (BPM). + */ int Tempo() { return uClock.getTempo(); } - // Set the clock tempo to a int between 1 and 400. + /** + * @brief Set the clock tempo. + * + * @param tempo The new tempo in beats per minute (BPM). + */ void SetTempo(int tempo) { return uClock.setTempo(tempo); } - // Record an external clock tick received to process external/internal syncronization. + /** + * @brief Manually trigger a clock tick. + * + * This should be called when in an external clock mode to register an incoming + * clock pulse and drive the internal timing. + */ void Tick() { uClock.clockMe(); } - // Start the internal clock. + /** + * @brief Starts the clock. + */ void Start() { uClock.start(); } - // Stop internal clock clock. + /** + * @brief Stops (pauses) the clock. + */ void Stop() { uClock.stop(); } - // Reset all clock counters to 0. + /** + * @brief Resets all clock counters to zero. + */ void Reset() { uClock.resetCounters(); } - // Returns true if the clock is not running. + /** + * @brief Checks if the clock is currently paused. + * + * @return true if the clock is stopped/paused. + * @return false if the clock is running. + */ bool IsPaused() { return uClock.clock_state == uClock.PAUSED; } diff --git a/encoder.h b/encoder.h index 85d52f1..ad0ff76 100644 --- a/encoder.h +++ b/encoder.h @@ -4,10 +4,11 @@ * @brief Class for interacting with encoders. * @version 0.1 * @date 2025-04-19 - * + * * @copyright MIT - (c) 2025 - Adam Wonak - adam.wonak@gmail.com * */ + #ifndef ENCODER_DIR_H #define ENCODER_DIR_H @@ -16,6 +17,9 @@ #include "button.h" #include "peripherials.h" +/** + * @brief Class for interacting with a rotary encoder that has a push button. + */ class Encoder { protected: typedef void (*CallbackFunction)(void); @@ -32,22 +36,57 @@ class Encoder { } ~Encoder() {} - // Set to true if the encoder read direction should be reversed. + /** + * @brief Set the direction of the encoder. + * + * @param reversed Set to true to reverse the direction of rotation. + */ void SetReverseDirection(bool reversed) { reversed_ = reversed; } + + /** + * @brief Attach a handler for the encoder button press. + * + * This callback is triggered on a simple press and release of the button, + * without any rotation occurring during the press. + * + * @param f The callback function to execute when a button press. + */ void AttachPressHandler(CallbackFunction f) { on_press = f; } + /** + * @brief Attach a handler for encoder rotation. + * + * This callback is triggered when the encoder is rotated while the button is not pressed. + * + * @param f The callback function to execute on rotation. It receives an integer + * representing the change in position (can be positive or negative). + */ void AttachRotateHandler(RotateCallbackFunction f) { on_rotate = f; } + /** + * @brief Attach a handler for rotation while the button is pressed. + * + * This callback is triggered when the encoder is rotated while the button is being held down. + * + * @param f The callback function to execute. It receives an integer + * representing the change in position. + */ void AttachPressRotateHandler(RotateCallbackFunction f) { on_press_rotate = f; } + /** + * @brief Processes encoder and button events. + * + * This method should be called repeatedly in the main loop to check for state + * changes (rotation, button presses) and dispatch the appropriate callbacks. + */ void Process() { // Get encoder position change amount. int encoder_rotated = _rotate_change() != 0; @@ -91,7 +130,6 @@ class Encoder { int position = encoder_.getPosition(); unsigned long ms = encoder_.getMillisBetweenRotations(); - // Validation (TODO: add debounce check). if (previous_pos_ == position) { return 0; }