Doxygen across new sections

Author: brentru

.gitignore

@@ -52,4 +52,6 @@ data/
 
 # Misc. Data
 tests/
-venv/
+venv/
+
+Doxyfile

src/Wippersnapper.h

@@ -47,16 +47,24 @@
 // Define actual debug output functions when necessary.
 #ifdef WS_DEBUG
 #define WS_DEBUG_PRINT(...)                                                    \
-  { WS_PRINTER.print(__VA_ARGS__); } ///< Prints debug output.
+  {                                                                            \
+    WS_PRINTER.print(__VA_ARGS__);                                             \
+  } ///< Prints debug output.
 #define WS_DEBUG_PRINTLN(...)                                                  \
-  { WS_PRINTER.println(__VA_ARGS__); } ///< Prints line from debug output.
+  {                                                                            \
+    WS_PRINTER.println(__VA_ARGS__);                                           \
+  } ///< Prints line from debug output.
 #define WS_DEBUG_PRINTHEX(...)                                                 \
-  { WS_PRINTER.print(__VA_ARGS__, HEX); } ///< Prints debug output.
+  {                                                                            \
+    WS_PRINTER.print(__VA_ARGS__, HEX);                                        \
+  } ///< Prints debug output.
 #else
 #define WS_DEBUG_PRINT(...)                                                    \
-  {} ///< Prints debug output
+  {                                                                            \
+  } ///< Prints debug output
 #define WS_DEBUG_PRINTLN(...)                                                  \
-  {} ///< Prints line from debug output.
+  {                                                                            \
+  } ///< Prints line from debug output.
 #endif
 
 #define WS_DELAY_WITH_WDT(timeout)                                             \
@@ -127,12 +135,12 @@
 #include "display/ws_display_ui_helper.h"
 #endif
 
+#include "components/display/controller.h"
 #include "components/ds18x20/ws_ds18x20.h"
 #include "components/pixels/ws_pixels.h"
 #include "components/pwm/ws_pwm.h"
 #include "components/servo/ws_servo.h"
 #include "components/uart/ws_uart.h"
-#include "components/display/controller.h"
 
 #if defined(USE_TINYUSB)
 #include "provisioning/tinyusb/Wippersnapper_FS.h"
@@ -154,7 +162,7 @@
 #define TOPIC_INFO "/info/"       ///< Registration sub-topic
 #define TOPIC_SIGNALS "/signals/" ///< Signals sub-topic
 #define TOPIC_I2C "/i2c"          ///< I2C sub-topic
-#define TOPIC_DISPLAY "/display" ///< Display sub-topic (EPD, OLED, TFT, etc.)
+#define TOPIC_DISPLAY "/display"  ///< Display sub-topic (EPD, OLED, TFT, etc.)
 #define MQTT_TOPIC_PIXELS_DEVICE                                               \
   "/signals/device/pixel" ///< Pixels device->broker topic
 #define MQTT_TOPIC_PIXELS_BROKER                                               \
@@ -371,7 +379,8 @@ class Wippersnapper {
   ws_servo *_servoComponent;      ///< Instance of servo class
   ws_ds18x20 *_ds18x20Component;  ///< Instance of DS18x20 class
   ws_uart *_uartComponent;        ///< Instance of UART class
-  DisplayController *_displayController; ///< Instance of display controller class
+  DisplayController
+      *_displayController; ///< Instance of display controller class
 
   // TODO: does this really need to be global?
   uint8_t _macAddr[6];  /*!< Unique network iface identifier */
@@ -408,8 +417,10 @@ class Wippersnapper {
   char *_topic_signal_pixels_device = NULL; /*!< Topic carries pixel messages */
   char *_topic_signal_uart_brkr = NULL;     /*!< Topic carries UART messages */
   char *_topic_signal_uart_device = NULL;   /*!< Topic carries UART messages */
-  char *_topic_signal_display_brkr = NULL; /*!< Topic carries messages from a device to a broker. */
-  char *_topic_signal_display_device = NULL;   /*!< Topic carries messages from a broker to a device. */
+  char *_topic_signal_display_brkr =
+      NULL; /*!< Topic carries messages from a device to a broker. */
+  char *_topic_signal_display_device =
+      NULL; /*!< Topic carries messages from a broker to a device. */
 
   wippersnapper_signal_v1_CreateSignalRequest
       _incomingSignalMsg; /*!< Incoming signal message from broker */
@@ -436,7 +447,8 @@ class Wippersnapper {
   wippersnapper_signal_v1_UARTRequest
       msgSignalUART; ///< UARTReq wrapper message
 
-  wippersnapper_signal_v1_DisplayRequest msgSignalDisplay;
+  wippersnapper_signal_v1_DisplayRequest
+      msgSignalDisplay; ///< DisplayRequest wrapper message
 
   char *throttleMessage; /*!< Pointer to throttle message data. */
   int throttleTime;      /*!< Total amount of time to throttle the device, in
@@ -498,8 +510,8 @@ class Wippersnapper {
       *_topic_signal_pixels_sub; /*!< Subscribes to pixel device topic. */
   Adafruit_MQTT_Subscribe
       *_topic_signal_uart_sub; /*!< Subscribes to signal's UART topic. */
-  Adafruit_MQTT_Subscribe
-      *_topic_signal_display_sub; /*!< Subscription callback for display topic. */
+  Adafruit_MQTT_Subscribe *_topic_signal_display_sub; /*!< Subscription callback
+                                                         for display topic. */
 
   Adafruit_MQTT_Subscribe
       *_err_sub; /*!< Subscription to Adafruit IO Error topic. */

src/Wippersnapper_demo.ino.cpp

@@ -18,30 +18,65 @@
 #include "Adafruit_ThinkInk.h"
 #include "Wippersnapper.h"
 
+/*!
+    @brief  Abstract base class for display drivers.
+            This class provides a common interface for all display drivers,
+            allowing them to be used interchangeably.
+*/
 class dispDrvBase {
 public:
+  /*!
+      @brief  Constructor for the base display driver for E-Ink displays.
+      @param  dc
+              Data/Command pin for the display.
+      @param  rst
+              Reset pin for the display.
+      @param  cs
+              Chip Select pin for the display.
+      @param  sram_cs
+              Optional SRAM Chip Select pin for E-Ink displays that support it.
+      @param  busy
+              Optional Busy pin for the display.
+  */
   dispDrvBase(int16_t dc, int16_t rst, int16_t cs, int16_t sram_cs = -1,
               int16_t busy = -1)
       : _pin_dc(dc), _pin_rst(rst), _pin_cs(cs), _pin_sram_cs(sram_cs),
-        _pin_busy(busy) {
-    // Constructor implementation (if we need one)
-  }
+        _pin_busy(busy) {}
 
-  virtual ~dispDrvBase() {
-    // Destructor implementation (if we need one)
-  };
+  /*!
+      @brief  Destructor for the base display driver.
+              This destructor is virtual to allow derived classes to clean up
+              resources properly.
+  */
+  virtual ~dispDrvBase() {}
 
+  /*!
+      @brief  Attempts to initialize a ThinkInk EPD driver.
+      @param  mode
+              The ThinkInk mode to use for the display.
+      @param  reset
+              Whether to reset the display before initialization.
+      @return True if the display was initialized successfully, false otherwise.
+  */
   virtual bool begin(thinkinkmode_t mode, bool reset = true);
 
+  /*!
+      @brief  Writes a message to the display.
+      @param  message
+              The message to write to the display.
+      @note   MUST be implemented by derived classes.
+  */
   virtual void writeMessage(const char *message) = 0;
 
 protected:
-  int16_t _pin_dc;
-  int16_t _pin_rst;
-  int16_t _pin_cs;
-  int16_t _pin_busy;
-  int16_t _pin_sram_cs; // for optional EPD SRAM chip select
-  uint8_t _text_sz = 1; ///< Text size for display messages
+  int16_t _pin_dc;      ///< Data/Command pin
+  int16_t _pin_rst;     ///< Reset pin
+  int16_t _pin_cs;      ///< Chip Select pin
+  int16_t _pin_busy;    ///< Optional Busy pin
+  int16_t _pin_sram_cs; ///< Optional EPD SRAM chip select pin
+  uint8_t _text_sz = 1; ///< Text size for displaying a message
+  int16_t _height;      ///< Height of the display
+  int16_t _width;       ///< Width of the display
 };
 
 #endif // WS_DISP_DRV_BASE_H

src/components/display/drivers/dispDrvBase.h

@@ -1,5 +1,5 @@
 /*!
- * @file src/components/display/drivers/drvDispThinkInkGrayscale4Eaamfgn.h
+ * @file src/components/display/drivers/dispDrvThinkInkGrayscale4Eaamfgn.h
  *
  * Driver for ThinkInk 2.9" Grayscale 4-level EAAMFGN display (present on the
  * 2025 version of the Adafruit MagTag)
@@ -18,8 +18,25 @@
 
 #include "dispDrvBase.h"
 
+/*!
+    @brief  Driver for a ThinkInk 2.9" Grayscale 4-level EAAMFGN display.
+*/
 class drvDispThinkInkGrayscale4Eaamfgn : public dispDrvBase {
 public:
+  /*!
+      @brief  Constructor for the ThinkInk Grayscale 4-level EAAMFGN display
+               driver.
+      @param  dc
+              Data/Command pin for the display.
+      @param  rst
+              Reset pin for the display.
+      @param  cs
+              Chip Select pin for the display.
+      @param  sram_cs
+              Optional SRAM Chip Select pin for E-Ink displays that support it.
+      @param  busy
+              Optional Busy pin for the display.
+  */
   drvDispThinkInkGrayscale4Eaamfgn(int16_t dc, int16_t rst, int16_t cs,
                                    int16_t sram_cs = -1, int16_t busy = -1)
       : dispDrvBase(dc, rst, cs, sram_cs, busy), _display(nullptr) {}
@@ -31,6 +48,15 @@ class drvDispThinkInkGrayscale4Eaamfgn : public dispDrvBase {
     }
   }
 
+  /*!
+      @brief  Attempts to initialize the ThinkInk Grayscale 4-level EAAMFGN
+              display driver.
+      @param  mode
+              The ThinkInk mode to use for the display.
+      @param  reset
+              Whether to reset the display before initialization.
+      @return True if the display was initialized successfully, false otherwise.
+  */
   bool begin(thinkinkmode_t mode, bool reset = true) override {
     _display = new ThinkInk_290_Grayscale4_EAAMFGN(_pin_dc, _pin_rst, _pin_cs,
                                                    _pin_sram_cs, _pin_busy);
@@ -44,13 +70,22 @@ class drvDispThinkInkGrayscale4Eaamfgn : public dispDrvBase {
     _display->setTextSize(_text_sz);
     _display->setTextColor(EPD_BLACK);
     _display->setTextWrap(false);
+    _height = _display->height();
+    _width = _display->width();
     // Clear the display buffer
     _display->clearBuffer();
     _display->display();
 
     return true;
   }
 
+  /*!
+      @brief  Writes a message to the display.
+      @param  message
+              The message to write to the display.
+      @note   This method overrides the base class method to provide specific
+              functionality for the Think Ink Grayscale 4 EAAMGFGN driver.
+  */
   virtual void writeMessage(const char *message) override {
     if (_display == nullptr)
       return;
@@ -66,17 +101,23 @@ class drvDispThinkInkGrayscale4Eaamfgn : public dispDrvBase {
     uint16_t c_idx = 0;
     size_t msg_size = strlen(message);
     for (size_t i = 0; i < msg_size && c_idx < msg_size; i++) {
+      if (y_idx + line_height > _height)
+        break;
       if (message[i] == '\\' && i + 1 < msg_size &&
           (message[i + 1] == 'n' || message[i + 1] == 'r')) {
         // Handle \r\n sequence as a single newline
         if (message[i + 1] == 'r' && i + 3 < msg_size &&
             message[i + 2] == '\\' && message[i + 3] == 'n') {
           // Skip to the next line
+          if (y_idx + line_height > _height)
+            break;
           y_idx += line_height;
           _display->setCursor(0, y_idx);
           i += 3;
         } else if (message[i + 1] == 'n') {
           // Skip to the next line
+          if (y_idx + line_height > _height)
+            break;
           y_idx += line_height;
           _display->setCursor(0, y_idx);
           i++;

src/components/display/drivers/dispDrvThinkInkGrayscale4Eaamfgn.h

@@ -63,6 +63,8 @@ dispDrvBase *CreateDrvDisp(const char *driver_name, int16_t dc, int16_t rst,
 
 /*!
     @brief  Constructs a new DisplayHardware object
+    @param  name
+            The name of the hardware instance.
 */
 DisplayHardware::DisplayHardware(const char *name) {
   strncpy(_name, name, sizeof(_name) - 1);
@@ -74,7 +76,10 @@ DisplayHardware::DisplayHardware(const char *name) {
     @brief  Destructor
 */
 DisplayHardware::~DisplayHardware() {
-  // TODO
+  if (_drvDisp) {
+    delete _drvDisp;
+    _drvDisp = nullptr;
+  }
 }
 
 /*!
@@ -152,8 +157,8 @@ bool DisplayHardware::beginEPD(
   // TODO: Configure SPI bus selection (UNUSED AS OF RIGHT NOW)
 
   // Create display driver object using the factory function
-  _disp_drv_base = CreateDrvDisp(_name, dc, rst, cs, srcs, busy);
-  if (!_disp_drv_base) {
+  _drvDisp = CreateDrvDisp(_name, dc, rst, cs, srcs, busy);
+  if (!_drvDisp) {
     WS_DEBUG_PRINTLN("[display] Failed to create display driver!");
     return false; // Failed to create display driver
   }
@@ -165,10 +170,10 @@ bool DisplayHardware::beginEPD(
     WS_DEBUG_PRINTLN("[display] EPD mode: GRAYSCALE4");
   }
 
-  if (!_disp_drv_base->begin(epd_mode)) {
+  if (!_drvDisp->begin(epd_mode)) {
     WS_DEBUG_PRINTLN("[display] Failed to begin display driver!");
-    delete _disp_drv_base;
-    _disp_drv_base = nullptr;
+    delete _drvDisp;
+    _drvDisp = nullptr;
     return false;
   }
 
@@ -181,9 +186,14 @@ bool DisplayHardware::beginEPD(
 */
 const char *DisplayHardware::getName() { return _name; }
 
+/*!
+    @brief  Writes a message to the display.
+    @param  message
+            The message to display.
+*/
 void DisplayHardware::writeMessage(const char *message) {
-  if (_disp_drv_base) {
-    _disp_drv_base->writeMessage(message);
+  if (_drvDisp) {
+    _drvDisp->writeMessage(message);
   } else {
     WS_DEBUG_PRINTLN("[display] No display driver initialized!");
   }

src/components/display/hardware.cpp

@@ -20,14 +20,12 @@
 #include <functional>
 #include <map>
 
-/**************************************************************************/
 /*!
     @brief  Interface for interacting with display hardware (TFT, eInk,
             OLED, etc.)
             This class provides methods to initialize, write to, and
             manage the state of display hardware.
 */
-/**************************************************************************/
 class DisplayHardware {
 public:
   DisplayHardware(const char *name);
@@ -52,6 +50,6 @@ class DisplayHardware {
 private:
   char _name[64]; ///< Identifies the hardware instance
   wippersnapper_display_v1_DisplayType _type; ///< Display type
-  dispDrvBase *_disp_drv_base = nullptr;      ///< Base display driver
+  dispDrvBase *_drvDisp = nullptr;            ///< Base display driver
 };
 #endif // WS_DISPLAY_HARDWARE_H