SGP30/40: add fastTick 1Hz cadence, simplify caching, update docs

Author: mikeysklar

src/components/i2c/drivers/WipperSnapper_I2C_Driver.h

@@ -1414,8 +1414,8 @@ class WipperSnapper_I2C_Driver {
   long _ambientTempFPeriod = 0L; ///< The time period between reading the
                                  ///< ambient temp. (°F) sensor's value.
   long _ambientTempFPeriodPrv =
-      PERIOD_24HRS_AGO_MILLIS; ///< The time when the ambient temp. (°F) sensor
-                               ///< was last read.
+      PERIOD_24HRS_AGO_MILLIS;  ///< The time when the ambient temp. (°F) sensor
+                                ///< was last read.
   long _objectTempFPeriod = 0L; ///< The time period between reading the object
                                 ///< temp. (°F) sensor's value.
   long _objectTempFPeriodPrv =

src/components/i2c/drivers/WipperSnapper_I2C_Driver_SGP30.h

@@ -4,6 +4,8 @@
 #include "WipperSnapper_I2C_Driver.h"
 #include <Adafruit_SGP30.h>
 
+#define SGP30_FASTTICK_INTERVAL_MS 1000 ///< Enforce ~1 Hz cadence
+
 /**************************************************************************/
 /*!
     @brief  Class that provides a driver interface for a SGP30 sensor.
@@ -54,6 +56,7 @@ class WipperSnapper_I2C_Driver_SGP30 : public WipperSnapper_I2C_Driver {
     }
     _sgp30->IAQinit(); // start IAQ algorithm
     _did_measure = false;
+    _lastFastMs = millis() - SGP30_FASTTICK_INTERVAL_MS;
     return true;
   }
 
@@ -87,10 +90,22 @@ class WipperSnapper_I2C_Driver_SGP30 : public WipperSnapper_I2C_Driver {
 
   /*******************************************************************************/
   /*!
-      @brief  Performs a lightweight background poll for the SGP30.
-              Calls IAQmeasure() once and caches whether it succeeded.
-              Cached values (eCO2, TVOC) are then available via getEvent*().
-              No averaging or delay; must be non-blocking.
+      @brief  Performs background sampling for the SGP30.
+
+              This method enforces a ~1 Hz cadence recommended by the sensor
+              datasheet. On each call, it checks the elapsed time since the
+              last poll using `millis()`. If at least
+              SGP30_FASTTICK_INTERVAL_MS have passed, it performs a single
+              IAQ measurement and caches the result in `_did_measure`.
+
+              Cached values (eCO2, TVOC) are later returned by
+              `getEventECO2()` and `getEventTVOC()` without re-triggering I2C
+              traffic.
+
+      @note   Called automatically from
+              `WipperSnapper_Component_I2C::update()` once per loop iteration.
+              Must be non-blocking (no delays). The millis-based guard ensures
+              the sensor is not over-polled.
   */
   /*******************************************************************************/
   void fastTick() override {
@@ -99,8 +114,11 @@ class WipperSnapper_I2C_Driver_SGP30 : public WipperSnapper_I2C_Driver {
     if (!iaqEnabled())
       return;
 
-    // Only perform a single IAQ measurement and cache the result
-    _did_measure = _sgp30->IAQmeasure();
+    uint32_t now = millis();
+    if (now - _lastFastMs >= SGP30_FASTTICK_INTERVAL_MS) {
+      _did_measure = _sgp30->IAQmeasure();
+      _lastFastMs = now;
+    }
   }
 
 protected:
@@ -109,6 +127,9 @@ class WipperSnapper_I2C_Driver_SGP30 : public WipperSnapper_I2C_Driver {
   /** Whether we have a fresh IAQ measurement ready. */
   bool _did_measure = false;
 
+  /** Timestamp of last poll to enforce 1 Hz cadence. */
+  uint32_t _lastFastMs = 0;
+
   /*******************************************************************************/
   /*!
       @brief  Returns whether IAQ background sampling should be active.

src/components/i2c/drivers/WipperSnapper_I2C_Driver_SGP40.h

@@ -20,6 +20,8 @@
 #include <Adafruit_SGP40.h>
 #include <Wire.h>
 
+#define SGP40_FASTTICK_INTERVAL_MS 1000 ///< Enforce ~1 Hz cadence
+
 /**************************************************************************/
 /*!
     @brief  Class that provides a driver interface for the SGP40 sensor.
@@ -73,6 +75,7 @@ class WipperSnapper_I2C_Driver_SGP40 : public WipperSnapper_I2C_Driver {
     // Initialize cached values
     _rawValue = 0;
     _vocIdx = 0;
+    _lastFastMs = millis() - SGP40_FASTTICK_INTERVAL_MS;
     return true;
   }
 
@@ -110,9 +113,21 @@ class WipperSnapper_I2C_Driver_SGP40 : public WipperSnapper_I2C_Driver {
 
   /*******************************************************************************/
   /*!
-      @brief    Performs background sampling for the SGP40.
-                single poll (no averaging) and cache
-                results for getEventRaw()/getEventVOCIndex().
+      @brief  Performs background sampling for the SGP40.
+
+              This method enforces a ~1 Hz cadence recommended by the sensor
+              datasheet. On each call, it checks the elapsed time since the last
+              poll using `millis()`. If at least SGP40_FASTTICK_INTERVAL_MS ms
+              have passed, it reads a new raw value and VOC index from the
+     sensor and caches them in `_rawValue` and `_vocIdx`.
+
+              Cached results are later returned by `getEventRaw()` and
+              `getEventVOCIndex()` without re-triggering I2C traffic.
+
+      @note   Called automatically from
+              `WipperSnapper_Component_I2C::update()` once per loop iteration.
+              Must be non-blocking (no delays). The millis-based guard ensures
+              the sensor is not over-polled.
   */
   /*******************************************************************************/
   void fastTick() override {
@@ -121,17 +136,25 @@ class WipperSnapper_I2C_Driver_SGP40 : public WipperSnapper_I2C_Driver {
     if (!vocEnabled())
       return;
 
-    // Single poll and cache latest values (no cadence/averaging)
-    _rawValue = _sgp40->measureRaw();
-    _vocIdx = (uint16_t)_sgp40->measureVocIndex();
+    uint32_t now = millis();
+    if (now - _lastFastMs >= SGP40_FASTTICK_INTERVAL_MS) {
+      _rawValue = _sgp40->measureRaw();
+      _vocIdx = (int32_t)_sgp40->measureVocIndex();
+      _lastFastMs = now;
+    }
   }
 
 protected:
-  Adafruit_SGP40 *_sgp40; ///< SGP40
+  Adafruit_SGP40 *_sgp40; ///< Pointer to SGP40 sensor object
 
-  /** Cached latest measurements (no averaging). */
-  uint16_t _rawValue = 0;
-  uint16_t _vocIdx = 0; ///< VOC index value (0–500)
+  /**
+   * Cached latest measurements from the sensor.
+   * - _rawValue: raw sensor output (ticks)
+   * - _vocIdx: VOC Index (signed, per datasheet)
+   */
+  uint16_t _rawValue = 0;   ///< Raw sensor output (ticks)
+  int32_t _vocIdx = 0;      ///< VOC Index (signed, per datasheet)
+  uint32_t _lastFastMs = 0; ///< Last poll timestamp to enforce 1 Hz cadence
 
   /*******************************************************************************/
   /*!