From 8cd12dfdd22438d585bebc09e00d4cdefe0110bb Mon Sep 17 00:00:00 2001 From: brentru Date: Tue, 11 Feb 2025 10:40:16 -0500 Subject: [PATCH] Doxygen Pass 2/? --- src/Wippersnapper_V2.h | 6 ++- src/adapters/wifi/ws_wifi_esp32.h | 2 +- src/components/i2c/controller.cpp | 16 +++++- src/components/i2c/drivers/drvBase.h | 72 +++++++++++++++++++++++--- src/components/i2c/drivers/drvBme280.h | 7 ++- src/components/i2c/drivers/drvScd4x.h | 2 +- 6 files changed, 88 insertions(+), 17 deletions(-) diff --git a/src/Wippersnapper_V2.h b/src/Wippersnapper_V2.h index 52a3d695..aa3e4dae 100644 --- a/src/Wippersnapper_V2.h +++ b/src/Wippersnapper_V2.h @@ -24,7 +24,11 @@ #define WS_DEBUG ///< Define to enable debugging to serial terminal #define WS_PRINTER Serial ///< Where debug messages will be printed -// Define actual debug output functions when necessary. +/**************************************************************************/ +/*! + @brief Debug print macros +*/ +/**************************************************************************/ #ifdef WS_DEBUG #define WS_DEBUG_PRINT(...) \ { WS_PRINTER.print(__VA_ARGS__); } ///< Prints debug output. diff --git a/src/adapters/wifi/ws_wifi_esp32.h b/src/adapters/wifi/ws_wifi_esp32.h index b68f9c98..6c8fd289 100644 --- a/src/adapters/wifi/ws_wifi_esp32.h +++ b/src/adapters/wifi/ws_wifi_esp32.h @@ -1,5 +1,5 @@ /*! - * @file Wippersnapper_ESP32_V2.h + * @file ws_wifi_esp32.h * * This is a driver for using the ESP32's network interface * with Adafruit IO Wippersnapper. diff --git a/src/components/i2c/controller.cpp b/src/components/i2c/controller.cpp index 43c8880f..230cb4b6 100644 --- a/src/components/i2c/controller.cpp +++ b/src/components/i2c/controller.cpp @@ -14,7 +14,19 @@ */ #include "controller.h" -// lambda function to create drvBase driver +/*******************************************************************************/ +/*! + @brief lambda function to create a drvBase driver instance + @param i2c + The I2C interface. + @param addr + 7-bit device address. + @param mux_channel + The I2C multiplexer channel. + @param driver_name + The name of the driver. +*/ +/*******************************************************************************/ using FnCreateI2CDriver = std::function; @@ -329,7 +341,7 @@ static const std::map I2cFactory = { [](TwoWire *i2c, uint16_t addr, uint32_t mux_channel, const char *driver_name) -> drvBase * { return new drvVl6180x(i2c, addr, mux_channel, driver_name); - }}}; + }}}; ///< I2C driver factory /***********************************************************************/ /*! diff --git a/src/components/i2c/drivers/drvBase.h b/src/components/i2c/drivers/drvBase.h index 8dbaaa34..2e2feec2 100644 --- a/src/components/i2c/drivers/drvBase.h +++ b/src/components/i2c/drivers/drvBase.h @@ -36,6 +36,8 @@ public: The I2C hardware interface, default is Wire. @param address The I2C sensor's unique address. + @param driver_name + The name of the driver. */ /*******************************************************************************/ drvBase(TwoWire *i2c, uint16_t address, const char *driver_name) { @@ -60,6 +62,8 @@ public: @param mux_channel An optional channel number used to address a device on a I2C MUX. + @param driver_name + The name of the driver. */ /*******************************************************************************/ drvBase(TwoWire *i2c, uint16_t address, uint32_t mux_channel, @@ -98,16 +102,30 @@ public: /*******************************************************************************/ uint16_t GetAddress() { return _address; } + /*******************************************************************************/ + /*! + @brief Gets the I2C MUX address. + @returns The I2C MUX address. + */ + /*******************************************************************************/ uint32_t GetMuxAddress() { return _i2c_mux_addr; } + /*******************************************************************************/ + /*! + @brief Sets the I2C MUX address. + @param mux_address + The I2C MUX address. + */ + /*******************************************************************************/ void SetMuxAddress(uint32_t mux_address) { _i2c_mux_addr = mux_address; } /*******************************************************************************/ /*! @brief Set if the I2C driver has an alternative I2C bus. - @param has_alt_i2c_bus - True if the I2C driver requests to use an alternative I2C bus, - False otherwise. + @param scl_pin + The SCL pin for the alternative I2C bus. + @param sda_pin + The SDA pin for the alternative I2C bus. */ /*******************************************************************************/ void EnableAltI2CBus(char *scl_pin, char *sda_pin) { @@ -116,7 +134,20 @@ public: _has_alt_i2c_bus = true; } + /*******************************************************************************/ + /*! + @brief Gets the SCL pin for the alternative I2C bus. + @returns The SCL pin for the alternative I2C bus. + */ + /*******************************************************************************/ const char *GetPinSCL() { return _pin_scl; } + + /*******************************************************************************/ + /*! + @brief Gets the SDA pin for the alternative I2C bus. + @returns The SDA pin for the alternative I2C bus. + */ + /*******************************************************************************/ const char *GetPinSDA() { return _pin_sda; } /*******************************************************************************/ @@ -147,10 +178,10 @@ public: /*******************************************************************************/ /*! @brief Configures an i2c device's sensors. - @param sensors + @param sensor_types Pointer to an array of SensorType objects. - @param count - The number of active sensors on the device. + @param sensor_types_count + The number of active sensors to read from the device. */ /*******************************************************************************/ void EnableSensorReads(wippersnapper_sensor_SensorType *sensor_types, @@ -320,6 +351,13 @@ public: return false; } + /*******************************************************************************/ + /*! + @brief Base implementation - Selects a MUX channel for use with the + I2C device. + @param channel + The MUX channel to select. + */ virtual void SelectMUXChannel(uint8_t channel) { return; } /*******************************************************************************/ @@ -557,6 +595,17 @@ public: return false; } + /*******************************************************************************/ + /*! + @brief Reads a sensor's event from the i2c driver. + @param sensor_type + The sensor type to read. + @param sensors_event + Pointer to an Adafruit_Sensor event. + @returns True if the sensor event was obtained successfully, False + otherwise. + */ + /*******************************************************************************/ bool GetSensorEvent(wippersnapper_sensor_SensorType sensor_type, sensors_event_t *sensors_event) { auto it = SensorEventHandlers.find(sensor_type); @@ -565,7 +614,14 @@ public: return it->second(sensors_event); } - // Lambda function type for all GetEventX() function calls + /*******************************************************************************/ + /*! + @brief Function type for sensor event handlers + @param sensors_event_t* + Pointer to the sensor event structure to be filled + @returns True if event was successfully read, False otherwise + */ + /*******************************************************************************/ using fnGetEvent = std::function; // Maps SensorType to function calls @@ -673,7 +729,7 @@ public: {wippersnapper_sensor_SensorType_SENSOR_TYPE_TVOC, [this](sensors_event_t *event) -> bool { return this->getEventTVOC(event); - }}}; + }}}; ///< SensorType to function call map wippersnapper_sensor_SensorType _sensors[15]; ///< Sensors attached to the device. diff --git a/src/components/i2c/drivers/drvBme280.h b/src/components/i2c/drivers/drvBme280.h index 1e729861..3d87ead4 100644 --- a/src/components/i2c/drivers/drvBme280.h +++ b/src/components/i2c/drivers/drvBme280.h @@ -39,13 +39,12 @@ public: 7-bit device address. @param mux_channel The I2C MUX channel, if applicable. - @param mux_channel - The I2C multiplexer channel. @param driver_name The name of the driver. */ /*******************************************************************************/ - drvBme280(TwoWire *i2c, uint16_t sensorAddress, uint32_t mux_channel, const char* driver_name) + drvBme280(TwoWire *i2c, uint16_t sensorAddress, uint32_t mux_channel, + const char *driver_name) : drvBase(i2c, sensorAddress, mux_channel, driver_name) { _i2c = i2c; _address = sensorAddress; @@ -72,7 +71,7 @@ public: // attempt to initialize BME280 if (!_bme->begin(_address, _i2c)) return false; - + // Configure sensors _bme_temp = _bme->getTemperatureSensor(); if (_bme_temp == NULL) diff --git a/src/components/i2c/drivers/drvScd4x.h b/src/components/i2c/drivers/drvScd4x.h index a79a181d..c78e2640 100644 --- a/src/components/i2c/drivers/drvScd4x.h +++ b/src/components/i2c/drivers/drvScd4x.h @@ -1,5 +1,5 @@ /*! - * @file WipperSnapper_I2C_Driver_SCD4x.h + * @file drvScd4x.h * * Device driver for the SCD4X CO2, Temperature, and Humidity sensor. *