From 067c220e8743ccf11fa5ad63fdd54def0f0016ad Mon Sep 17 00:00:00 2001 From: brentru Date: Thu, 3 Oct 2024 11:16:28 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=A8=20WIP,=20analogio=20-=20Doxygen=20?= =?UTF-8?q?analogio=20classes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/components/analogIO/controller.cpp | 98 +++++++++++++++++++++++++- src/components/analogIO/controller.h | 2 +- src/components/analogIO/hardware.cpp | 66 +++++++++++++++++ src/components/analogIO/hardware.h | 15 ++-- src/components/analogIO/model.cpp | 82 +++++++++++++++++++-- src/components/analogIO/model.h | 8 ++- 6 files changed, 254 insertions(+), 17 deletions(-) diff --git a/src/components/analogIO/controller.cpp b/src/components/analogIO/controller.cpp index fba9d61e2..15785d171 100644 --- a/src/components/analogIO/controller.cpp +++ b/src/components/analogIO/controller.cpp @@ -14,6 +14,11 @@ */ #include "controller.h" +/***********************************************************************/ +/*! + @brief AnalogIO controller constructor +*/ +/***********************************************************************/ AnalogIOController::AnalogIOController() { _analogio_hardware = new AnalogIOHardware(); _analogio_model = new AnalogIOModel(); @@ -21,17 +26,48 @@ AnalogIOController::AnalogIOController() { SetRefVoltage(3.3); // Default to 3.3V } -AnalogIOController::~AnalogIOController() {} +/***********************************************************************/ +/*! + @brief AnalogIO controller destructor +*/ +/***********************************************************************/ +AnalogIOController::~AnalogIOController() { + delete _analogio_hardware; + delete _analogio_model; +} +/***********************************************************************/ +/*! + @brief Set the reference voltage for the analog pins + @param voltage + The reference voltage. +*/ +/***********************************************************************/ void AnalogIOController::SetRefVoltage(float voltage) { // To set the reference voltage, we call into the hardware _analogio_hardware->SetReferenceVoltage(voltage); } +/***********************************************************************/ +/*! + @brief Set the total number of analog pins present on the hardware. + @param total_pins + The hardware's total number of analog pins. +*/ +/***********************************************************************/ void AnalogIOController::SetTotalAnalogPins(uint8_t total_pins) { _total_analogio_pins = total_pins; } +/***********************************************************************/ +/*! + @brief Handles an AnalogIOAdd message from the broker and adds a + new analog pin to the controller. + @param stream + The nanopb input stream. + @return True if the pin was successfully added, False otherwise. +*/ +/***********************************************************************/ bool AnalogIOController::Handle_AnalogIOAdd(pb_istream_t *stream) { // Attempt to decode the incoming message into an AnalogIOAdd object if (!_analogio_model->DecodeAnalogIOAdd(stream)) { @@ -60,6 +96,15 @@ bool AnalogIOController::Handle_AnalogIOAdd(pb_istream_t *stream) { return true; } +/***************************************************************************/ +/*! + @brief Handles an AnalogIORemove message from the broker and removes + the requested analog pin from the controller. + @param stream + The nanopb input stream. + @return True if the pin was successfully removed, False otherwise. +*/ +/***************************************************************************/ bool AnalogIOController::Handle_AnalogIORemove(pb_istream_t *stream) { // Attempt to decode the incoming message into an AnalogIORemove object if (!_analogio_model->DecodeAnalogIORemove(stream)) { @@ -84,10 +129,32 @@ bool AnalogIOController::Handle_AnalogIORemove(pb_istream_t *stream) { return true; } +/***************************************************************************/ +/*! + @brief Checks if a pin's periodic timer has expired. + @param pin + The requested pin to check. + @param cur_time + The current time (called from millis()). + @return True if the pin's period has expired, False otherwise. +*/ +/***************************************************************************/ bool AnalogIOController::IsPinTimerExpired(analogioPin *pin, ulong cur_time) { return cur_time - pin->prv_period > pin->period; } +/***************************************************************************/ +/*! + @brief Encodes and publishes an AnalogIOEvent message to the broker. + @param pin + The pin to encode and publish. + @param value + The pin's value. + @param read_type + The type of read to perform on the pin. + @return True if the message was successfully encoded and published. +*/ +/***************************************************************************/ bool AnalogIOController::EncodePublishPinEvent( uint8_t pin, float value, wippersnapper_sensor_SensorType read_type) { char c_pin_name[12]; @@ -121,16 +188,43 @@ bool AnalogIOController::EncodePublishPinEvent( return true; } +/***************************************************************************/ +/*! + @brief Encodes and publishes an AnalogIOEvent message to the broker. + @param pin + The requested pin. + @param value + The pin's value. + @return True if the message was successfully encoded and published, + False othewise. +*/ +/***************************************************************************/ bool AnalogIOController::EncodePublishPinValue(uint8_t pin, uint16_t value) { return EncodePublishPinEvent(pin, (float)value, wippersnapper_sensor_SensorType_SENSOR_TYPE_RAW); } +/***************************************************************************/ +/*! + @brief Encodes and publishes an AnalogIOEvent message to the broker. + @param pin + The requested pin. + @param value + The pin's value, as a voltage. + @return True if the message was successfully encoded and published, + False othewise. +*/ +/***************************************************************************/ bool AnalogIOController::EncodePublishPinVoltage(uint8_t pin, float value) { return EncodePublishPinEvent( pin, value, wippersnapper_sensor_SensorType_SENSOR_TYPE_VOLTAGE); } +/***************************************************************************/ +/*! + @brief Update/polling loop for the AnalogIO controller. +*/ +/***************************************************************************/ void AnalogIOController::update() { // Bail-out if the vector is empty if (_analogio_pins.empty()) @@ -159,7 +253,7 @@ void AnalogIOController::update() { // Encode and publish the voltage value to the broker EncodePublishPinVoltage(pin.name, pin_value); } else { - WS_DEBUG_PRINTLN("ERROR: Invalid read mode for analog pin!"); + WS_DEBUG_PRINTLN("ERROR: Invalid read mode for analog pin!"); } } } \ No newline at end of file diff --git a/src/components/analogIO/controller.h b/src/components/analogIO/controller.h index 906edda4e..d046578c8 100644 --- a/src/components/analogIO/controller.h +++ b/src/components/analogIO/controller.h @@ -24,7 +24,7 @@ class AnalogIOHardware; ///< Forward declaration /** * @struct analogioPin - * @brief Structure repesenting an analogio pin on the device. + * @brief Represents a device's analogio pin. */ struct analogioPin { uint8_t name; ///< The pin's name. diff --git a/src/components/analogIO/hardware.cpp b/src/components/analogIO/hardware.cpp index 4fc073be9..76f783a6e 100644 --- a/src/components/analogIO/hardware.cpp +++ b/src/components/analogIO/hardware.cpp @@ -14,24 +14,61 @@ */ #include "hardware.h" +/***********************************************************************/ +/*! + @brief AnalogIO hardware constructor +*/ +/***********************************************************************/ AnalogIOHardware::AnalogIOHardware() { SetNativeADCResolution(); // Configure the device's native ADC resolution _scale_factor = 0; } +/***********************************************************************/ +/*! + @brief AnalogIO hardware destructor +*/ +/***********************************************************************/ AnalogIOHardware::~AnalogIOHardware() {} +/***********************************************************************/ +/*! + @brief Initializes an analog input pin. + @param pin + The requested pin. +*/ +/***********************************************************************/ void AnalogIOHardware::InitPin(uint8_t pin) { pinMode(pin, INPUT); } +/***********************************************************************/ +/*! + @brief Deinitializes an analog input pin and frees it for + other uses. + @param pin + The requested pin. +*/ +/***********************************************************************/ void AnalogIOHardware::DeinitPin(uint8_t pin) { pinMode(pin, INPUT); // set to a hi-z floating pin } +/*************************************************************************/ +/*! + @brief Sets the hardware's reference voltage for reading analog pins + @param voltage + The reference voltage. +*/ +/*************************************************************************/ void AnalogIOHardware::SetReferenceVoltage(float voltage) { _ref_voltage = voltage; _voltage_scale_factor = _ref_voltage / 65536; } +/*************************************************************************/ +/*! + @brief Configures the hardware's native ADC resolution. +*/ +/*************************************************************************/ void AnalogIOHardware::SetNativeADCResolution() { _is_adc_resolution_scaled = false; #if defined(ARDUINO_ARCH_SAMD) @@ -49,12 +86,25 @@ void AnalogIOHardware::SetNativeADCResolution() { #endif } +/*************************************************************************/ +/*! + @brief Sets the hardware ADC's resolution. + @param resolution + The requested resolution, in bits. +*/ +/*************************************************************************/ void AnalogIOHardware::SetResolution(uint8_t resolution) { _adc_resolution = resolution; // Calculate (or re-calculate) the scale factor when we set the resolution CalculateScaleFactor(); } +/*************************************************************************/ +/*! + @brief Calculates a factor used by the hardware for scaling + the ADC's resolution. +*/ +/*************************************************************************/ void AnalogIOHardware::CalculateScaleFactor() { if (!_is_adc_resolution_scaled) return; @@ -66,6 +116,14 @@ void AnalogIOHardware::CalculateScaleFactor() { } } +/*************************************************************************/ +/*! + @brief Gets the "raw" value of an analog pin from the ADC. + @param pin + The requested pin. + @return The pin's value. +*/ +/*************************************************************************/ uint16_t AnalogIOHardware::GetPinValue(uint8_t pin) { // Get the pin's value using Arduino API uint16_t value = analogRead(pin); @@ -80,6 +138,14 @@ uint16_t AnalogIOHardware::GetPinValue(uint8_t pin) { return value; } +/*************************************************************************/ +/*! + @brief Calculates the voltage of an analog pin. + @param raw_value + The pin's raw value. + @return The pin's voltage, in Volts. +*/ +/*************************************************************************/ float AnalogIOHardware::CalculatePinVoltage(uint16_t raw_value) { float voltage = raw_value * _voltage_scale_factor; return voltage; diff --git a/src/components/analogIO/hardware.h b/src/components/analogIO/hardware.h index 61ef7aac9..6cac98b18 100644 --- a/src/components/analogIO/hardware.h +++ b/src/components/analogIO/hardware.h @@ -29,7 +29,6 @@ class AnalogIOHardware { void SetResolution(uint8_t resolution); void SetReferenceVoltage(float voltage); void CalculateScaleFactor(); - // Arduino/Wiring API void InitPin(uint8_t pin); void DeinitPin(uint8_t pin); @@ -37,11 +36,13 @@ class AnalogIOHardware { float CalculatePinVoltage(uint16_t raw_voltage); private: - uint8_t _native_adc_resolution; - uint8_t _adc_resolution; - int _scale_factor; - bool _is_adc_resolution_scaled; - float _ref_voltage; - float _voltage_scale_factor; + uint8_t _native_adc_resolution; ///< Hardware's native ADC resolution. + uint8_t _adc_resolution; ///< Requested ADC resolution. + int _scale_factor; ///< Factor used for scaling the ADC's resolution. + bool _is_adc_resolution_scaled; ///< True if the ADC's resolution is scaled, + ///< False otherwise. + float _ref_voltage; ///< Reference voltage for reading analog pins. + float _voltage_scale_factor; ///< Scaling factor used for calculating the + ///< pin's voltage. }; #endif // WS_ANALOGIO_HARDWARE_H \ No newline at end of file diff --git a/src/components/analogIO/model.cpp b/src/components/analogIO/model.cpp index 1e58f0ab7..76e6ef35f 100644 --- a/src/components/analogIO/model.cpp +++ b/src/components/analogIO/model.cpp @@ -14,46 +14,100 @@ */ #include "model.h" -// TODO! Implement the AnalogIOModel class - +/***********************************************************************/ +/*! + @brief AnalogIOModel constructor +*/ +/***********************************************************************/ AnalogIOModel::AnalogIOModel() { _msg_AnalogioAdd = wippersnapper_analogio_AnalogIOAdd_init_default; } +/***********************************************************************/ +/*! + @brief AnalogIOModel destructor +*/ +/***********************************************************************/ AnalogIOModel::~AnalogIOModel() {} +/***********************************************************************/ +/*! + @brief Decodes an AnalogIOAdd message from a stream into an + AnalogIOAdd message struct. + @param stream + The pb_istream_t stream to decode. + @return True if successful, False otherwise. +*/ +/***********************************************************************/ bool AnalogIOModel::DecodeAnalogIOAdd(pb_istream_t *stream) { // Zero-out the AnalogIOAdd message struct. to ensure we don't have any old // data _msg_AnalogioAdd = wippersnapper_analogio_AnalogIOAdd_init_default; - // Decode the stream into a AnalogIOAdd message return pb_decode(stream, wippersnapper_analogio_AnalogIOAdd_fields, &_msg_AnalogioAdd); } +/***********************************************************************/ +/*! + @brief Gets an AnalogIOAdd message struct. + @return Pointer to an AnalogIOAdd message struct. +*/ +/***********************************************************************/ wippersnapper_analogio_AnalogIOAdd *AnalogIOModel::GetAnalogIOAddMsg() { return &_msg_AnalogioAdd; } +/***********************************************************************/ +/*! + @brief Decodes an AnalogIORemove message from a stream into an + AnalogIORemove message struct. + @param stream + The pb_istream_t stream to decode. + @return True if successful, False otherwise. +*/ +/***********************************************************************/ bool AnalogIOModel::DecodeAnalogIORemove(pb_istream_t *stream) { // Zero-out the AnalogIORemove message struct. to ensure we don't have any old // data _msg_AnalogioRemove = wippersnapper_analogio_AnalogIORemove_init_default; - // Decode the stream into a AnalogIORemove message return pb_decode(stream, wippersnapper_analogio_AnalogIORemove_fields, &_msg_AnalogioRemove); } +/*****************************************************************************/ +/*! + @brief Gets an AnalogIORemove message struct. + @return Pointer to an AnalogIORemove message struct. +*/ +/*****************************************************************************/ wippersnapper_analogio_AnalogIORemove *AnalogIOModel::GetAnalogIORemoveMsg() { return &_msg_AnalogioRemove; } +/*****************************************************************************/ +/*! + @brief Gets an AnalogIOEvent message struct. + @return Pointer to an AnalogIOEvent message struct. +*/ +/*****************************************************************************/ wippersnapper_analogio_AnalogIOEvent *AnalogIOModel::GetAnalogIOEvent() { return &_msg_AnalogioEvent; } +/*****************************************************************************/ +/*! + @brief Encodes an AnalogIOEvent message. + @param pin_name + The requested pin's name. + @param pin_value + The value of the pin. + @param read_type + The type of sensor event to encode. + @return True if successful, False otherwise. +*/ +/*****************************************************************************/ bool AnalogIOModel::EncodeAnalogIOEvent( char *pin_name, float pin_value, wippersnapper_sensor_SensorType read_type) { @@ -82,11 +136,31 @@ bool AnalogIOModel::EncodeAnalogIOEvent( &_msg_AnalogioEvent); } +/********************************************************************************/ +/*! + @brief Encodes an AnalogIOEvent message with a raw pin value. + @param pin_name + The requested pin's name. + @param pin_value + The value of the pin. + @return True if successful, False otherwise. +*/ +/********************************************************************************/ bool AnalogIOModel::EncodeAnalogIOEventRaw(char *pin_name, int16_t pin_value) { return EncodeAnalogIOEvent(pin_name, (float)pin_value, wippersnapper_sensor_SensorType_SENSOR_TYPE_RAW); } +/********************************************************************************/ +/*! + @brief Encodes an AnalogIOEvent message with a voltage pin value. + @param pin_name + The requested pin's name. + @param pin_value + The value of the pin. + @return True if successful, False otherwise. +*/ +/********************************************************************************/ bool AnalogIOModel::EncodeAnalogIOEventVoltage(char *pin_name, float pin_value) { return EncodeAnalogIOEvent( diff --git a/src/components/analogIO/model.h b/src/components/analogIO/model.h index db982fc67..8d6f2a441 100644 --- a/src/components/analogIO/model.h +++ b/src/components/analogIO/model.h @@ -40,8 +40,10 @@ class AnalogIOModel { wippersnapper_analogio_AnalogIOEvent *GetAnalogIOEvent(); private: - wippersnapper_analogio_AnalogIOAdd _msg_AnalogioAdd; - wippersnapper_analogio_AnalogIORemove _msg_AnalogioRemove; - wippersnapper_analogio_AnalogIOEvent _msg_AnalogioEvent; + wippersnapper_analogio_AnalogIOAdd _msg_AnalogioAdd; ///< AnalogIOAdd message + wippersnapper_analogio_AnalogIORemove + _msg_AnalogioRemove; ///< AnalogIORemove message + wippersnapper_analogio_AnalogIOEvent + _msg_AnalogioEvent; ///< AnalogIOEvent message }; #endif // WS_DIGITALIO_MODEL_H \ No newline at end of file