Telemetry: put the reading history behind a storage interface

TelemetryStore<T> replaces the fixed in-RAM array inline in the module.
at() copies rather than returning a reference, so a backing store need not
be memory the caller can point into, and indices stay logical and
oldest-first.

RamTelemetryStore keeps the ring on the heap; over 2 KB that is PSRAM on
ESP32 via heap_caps_malloc_extmem_enable(). Capacity follows
MESHTASTIC_MEM_CLASS: 64 readings on PSRAM boards, 8 on nRF52.

FileTelemetryStore keeps a fixed-size ring in a preallocated file, so
readings outlive a reboot or deep sleep. The file never grows, slots are
overwritten in place, and a header records the payload size so a build with
a different struct layout rebuilds rather than decoding nonsense. The
filesystem is a template parameter defaulting to FSCom. Enabled by defining
AIR_QUALITY_TELEMETRY_HISTORY_PATH; falls back to RAM if the file cannot be
opened.

One contract test drives both backends. Verified on Portduino only: the
read-write open mode differs between the string-mode and flag-mode
filesystem backends, so nRF52 and STM32 need a hardware check before any
variant enables the file store there.

Author: caveman99

src/modules/Telemetry/AirQualityTelemetry.cpp

@@ -12,7 +12,11 @@
 #include "Router.h"
 #include "TransmitHistory.h"
 #include "UnitConversions.h"
+#include "UptimeClock.h"
 #include "detect/ScanI2CTwoWire.h"
+#ifdef AIR_QUALITY_TELEMETRY_HISTORY_PATH
+#include "FileTelemetryStore.h"
+#endif
 #include "gps/RTC.h"
 #include "graphics/ScreenFonts.h"
 #include "graphics/SharedUIDisplay.h"
@@ -175,8 +179,7 @@ int32_t AirQualityTelemetryModule::runOnce()
             return disable();
         }
 
-        // The local device-to-phone loop runs at its own near-realtime cadence; air_quality_interval
-        // paces only what goes on air, and keeps the online-node scaling it has always had.
+        // air_quality_interval paces only what goes on air; the local loop has its own cadence.
         const uint32_t meshIntervalMs = Default::getConfiguredOrDefaultMsScaled(
             moduleConfig.telemetry.air_quality_interval, default_telemetry_broadcast_interval_secs, numOnlineNodes);
 
@@ -186,9 +189,9 @@ int32_t AirQualityTelemetryModule::runOnce()
         const bool meshAllowed =
             airTime->isTxAllowedChannelUtil(config.device.role != meshtastic_Config_DeviceConfig_Role_SENSOR) &&
             airTime->isTxAllowedAirUtil();
-        const bool meshDue = (lastMeshTelemetry == 0) || !Throttle::isWithinTimespanMs(lastMeshTelemetry, meshIntervalMs);
+        const bool meshDue = (lastMeshTelemetry == 0) || Throttle::hasElapsed(lastMeshTelemetry, meshIntervalMs);
 
-        if (shouldReadSensors(everRead, millis(), lastReadMs, localLoopIntervalMs, service->isToPhoneQueueEmpty(),
+        if (shouldReadSensors(everRead, Time::getMillis(), lastReadMs, localLoopIntervalMs, service->isToPhoneQueueEmpty(),
                               meshDue && meshAllowed)) {
             const int32_t warmingUpMs = warmUpSensors();
             if (warmingUpMs > 0)
@@ -200,8 +203,8 @@ int32_t AirQualityTelemetryModule::runOnce()
         // Send to sleep sensors that can be to save power
         for (TelemetrySensor *sensor : sensors) {
             if (sensor->isActive() && sensor->canSleep()) {
-                // Measured against the local loop, not the on-air interval: a sensor that cannot warm
-                // back up within one loop would never produce a reading if it were slept
+                // Against the local loop, not the on-air interval: a sensor that cannot warm back up
+                // within one loop would never produce a reading if it were slept
                 if (sensor->wakeUpTimeMs() < (int32_t)localLoopIntervalMs) {
                     LOG_DEBUG("Disabling %s until next period", sensor->sensorName);
                     sensor->sleep();
@@ -211,13 +214,12 @@ int32_t AirQualityTelemetryModule::runOnce()
             }
         }
 
-        if (shouldSendToMesh(history.hasUnpublishedNewest(TELEMETRY_PUBLISHED_MESH), meshDue, meshAllowed,
+        if (shouldSendToMesh(history->hasUnpublishedNewest(TELEMETRY_PUBLISHED_MESH), meshDue, meshAllowed,
                              isPowerSavingSensor())) {
-            // Called even with nothing latched: sendTelemetry() also arms the pre-sleep sequence a
-            // power-saving SENSOR needs to get back to deep sleep
+            // Called even with nothing to send: sendTelemetry() arms the power-saving SENSOR's sleep
             if (sendTelemetry(NODENUM_BROADCAST, false) && transmitHistory)
                 transmitHistory->setLastSentToMesh(TX_HISTORY_KEY_AIR_QUALITY_TELEMETRY);
-        } else if (history.hasUnpublishedNewest(TELEMETRY_PUBLISHED_PHONE) && service->isToPhoneQueueEmpty()) {
+        } else if (history->hasUnpublishedNewest(TELEMETRY_PUBLISHED_PHONE) && service->isToPhoneQueueEmpty()) {
             // Mesh transmission isn't due yet, but we can still update the phone
             sendTelemetry(NODENUM_BROADCAST, true);
         }
@@ -229,9 +231,8 @@ int32_t AirQualityTelemetryModule::runOnce()
         return FIVE_SECONDS_MS;
     }
 
-    // Cadence is driven by lastReadMs, measured from the read itself, so a sensor warm-up sits
-    // between two reads rather than being subtracted from the interval. Costs a few seconds of drift
-    // per cycle and saves tracking it.
+    // Cadence runs from the read itself, so a warm-up sits between two reads. Costs a few seconds
+    // of drift per cycle and saves tracking it.
     return min(localLoopIntervalMs, result);
 }
 
@@ -240,6 +241,7 @@ bool AirQualityTelemetryModule::shouldReadSensors(bool everRead, uint32_t nowMs,
 {
     if (!everRead)
         return true;
+    // Subtract-first, as Throttle::hasElapsed() does, so the 32-bit wrap cancels
     return (phoneQueueEmpty || meshPublishDue) && (nowMs - lastReadMs) >= localIntervalMs;
 }
 
@@ -254,8 +256,7 @@ int32_t AirQualityTelemetryModule::warmUpSensors()
 {
     int32_t pendingMs = 0;
 
-    // Every sensor is woken in the same pass: one with a long warm-up used to return early and keep
-    // the others from ever starting theirs
+    // All in one pass: a long warm-up used to return early and starve the others
     for (TelemetrySensor *sensor : sensors) {
         if (!sensor->canSleep()) {
             LOG_DEBUG("%s: no sleep support, skip", sensor->sensorName);
@@ -276,19 +277,36 @@ int32_t AirQualityTelemetryModule::warmUpSensors()
     return pendingMs;
 }
 
+void AirQualityTelemetryModule::openHistory()
+{
+#ifdef AIR_QUALITY_TELEMETRY_HISTORY_PATH
+    auto *persistent = makeFileTelemetryStore<meshtastic_AirQualityMetrics>(
+        AIR_QUALITY_TELEMETRY_HISTORY_PATH, AIR_QUALITY_TELEMETRY_HISTORY_SIZE, AIR_QUALITY_TELEMETRY_HISTORY_FS);
+    if (persistent->isUsable()) {
+        history = persistent;
+        return;
+    }
+
+    // No card, full filesystem, whatever: measuring into RAM beats not measuring
+    delete persistent;
+    LOG_WARN("AQ history: %s unusable, keeping readings in RAM", AIR_QUALITY_TELEMETRY_HISTORY_PATH);
+#endif
+
+    history = new RamTelemetryStore<meshtastic_AirQualityMetrics>(AIR_QUALITY_TELEMETRY_HISTORY_SIZE);
+}
+
 void AirQualityTelemetryModule::captureReading()
 {
     meshtastic_Telemetry m = meshtastic_Telemetry_init_zero;
 
     if (getAirQualityTelemetry(&m)) {
-        history.push(m.variant.air_quality_metrics, m.time);
+        history->push(m.variant.air_quality_metrics, m.time);
     } else {
         LOG_WARN("AQ read failed, keep the previous reading");
     }
 
-    // Stamped either way, so a sensor that keeps failing retries on the read interval instead of on
-    // every poll
-    lastReadMs = millis();
+    // Stamped either way, so a failing sensor retries on the interval rather than every poll
+    lastReadMs = Time::getMillis();
     everRead = true;
 }
 
@@ -434,8 +452,7 @@ bool AirQualityTelemetryModule::getAirQualityTelemetry(meshtastic_Telemetry *m)
     // There, if any sensor fails to read - valid = false.
     bool valid = false;
     bool hasSensor = false;
-    // getTime() falls back to uptime-as-epoch when no clock has been set, which would stamp the
-    // reading with a bogus 1970 date. 0 lets the receiver substitute its own receive time.
+    // getTime() falls back to uptime-as-epoch when unset; 0 lets the receiver use its rx time
     m->time = getValidTime(RTCQualityDevice);
     m->which_variant = meshtastic_Telemetry_air_quality_metrics_tag;
     m->variant.air_quality_metrics = meshtastic_AirQualityMetrics_init_zero;
@@ -472,17 +489,18 @@ meshtastic_MeshPacket *AirQualityTelemetryModule::allocReply()
         }
         // Check for a request for air quality metrics
         if (decoded->which_variant == meshtastic_Telemetry_air_quality_metrics_tag) {
-            // Answer from what the local loop already measured. Reading the sensors here instead
-            // would block on I2C and return nothing useful while they are asleep or warming up.
-            if (history.isEmpty()) {
+            // From the loop's last reading: reading here would block on I2C and return nothing
+            // useful while the sensors are asleep or warming up.
+            TelemetryReading<meshtastic_AirQualityMetrics> reading;
+            if (!history->newest(reading)) {
                 LOG_INFO("No air quality reading yet, no reply to request");
                 return NULL;
             }
 
             meshtastic_Telemetry m = meshtastic_Telemetry_init_zero;
             m.which_variant = meshtastic_Telemetry_air_quality_metrics_tag;
-            m.time = history.newest().time;
-            m.variant.air_quality_metrics = history.newest().metrics;
+            m.time = reading.time;
+            m.variant.air_quality_metrics = reading.metrics;
             LOG_INFO("Air quality telemetry reply to request");
             return allocDataProtobuf(m);
         }
@@ -514,13 +532,14 @@ bool AirQualityTelemetryModule::sendTelemetry(NodeNum dest, bool phoneOnly)
 {
     bool sent = false;
     const TelemetryPublishChannel channel = phoneOnly ? TELEMETRY_PUBLISHED_PHONE : TELEMETRY_PUBLISHED_MESH;
+    TelemetryReading<meshtastic_AirQualityMetrics> reading;
 
-    // Never send the same reading twice to the same destination
-    if (history.hasUnpublishedNewest(channel)) {
+    // One fetch then check the mask: on a file-backed store each read costs an open
+    if (history->newest(reading) && !(reading.publishedMask & channel)) {
         meshtastic_Telemetry m = meshtastic_Telemetry_init_zero;
         m.which_variant = meshtastic_Telemetry_air_quality_metrics_tag;
-        m.time = history.newest().time;
-        m.variant.air_quality_metrics = history.newest().metrics;
+        m.time = reading.time;
+        m.variant.air_quality_metrics = reading.metrics;
 
         logTelemetry(m);
 
@@ -543,13 +562,13 @@ bool AirQualityTelemetryModule::sendTelemetry(NodeNum dest, bool phoneOnly)
             if (phoneOnly) {
                 LOG_INFO("Sending packet to phone");
                 service->sendToPhone(p);
-                history.markNewestPublished(TELEMETRY_PUBLISHED_PHONE);
+                history->markNewestPublished(TELEMETRY_PUBLISHED_PHONE);
             } else {
                 LOG_INFO("Sending packet to mesh");
                 service->sendToMesh(p, RX_SRC_LOCAL, true);
-                history.markNewestPublished(TELEMETRY_PUBLISHED_MESH);
+                history->markNewestPublished(TELEMETRY_PUBLISHED_MESH);
                 // ccToPhone above hands the phone this very reading, no separate phone send needed
-                history.markNewestPublished(TELEMETRY_PUBLISHED_PHONE);
+                history->markNewestPublished(TELEMETRY_PUBLISHED_PHONE);
 
                 if (isPowerSavingSensor()) {
                     meshtastic_ClientNotification *notification = clientNotificationPool.allocZeroed();

src/modules/Telemetry/AirQualityTelemetry.h

@@ -10,18 +10,28 @@
 #define AIR_QUALITY_TELEMETRY_MODULE_ENABLE 0
 #endif
 
-// How many local-loop readings to retain between offloads. Sized to roughly one LoRa frame's worth:
-// a populated AirQualityMetrics encodes to ~35 bytes inside a TelemetryRecord, so about six fit the
-// 233-byte Data.payload limit. Each slot costs sizeof(TelemetryReading<meshtastic_AirQualityMetrics>),
-// ~216 bytes; a variant short on RAM can lower this, one with room to spare can raise it.
+// Readings retained between offloads, ~216 bytes each. Floor is one LoRa frame's worth (~6 fit
+// Data.payload); PSRAM boards go past that for free, the ring is heap-allocated.
 #ifndef AIR_QUALITY_TELEMETRY_HISTORY_SIZE
+#if MESHTASTIC_MEM_CLASS >= MEM_CLASS_LARGE
+#define AIR_QUALITY_TELEMETRY_HISTORY_SIZE 64
+#elif MESHTASTIC_MEM_CLASS >= MEM_CLASS_MEDIUM
+#define AIR_QUALITY_TELEMETRY_HISTORY_SIZE 16
+#else
 #define AIR_QUALITY_TELEMETRY_HISTORY_SIZE 8
 #endif
+#endif
+
+// Define AIR_QUALITY_TELEMETRY_HISTORY_PATH to persist readings instead of keeping them in RAM;
+// see the filesystem-choice note in FileTelemetryStore.h. Falls back to RAM if it cannot be opened.
+#ifndef AIR_QUALITY_TELEMETRY_HISTORY_FS
+#define AIR_QUALITY_TELEMETRY_HISTORY_FS FSCom
+#endif
 
 #include "../mesh/generated/meshtastic/telemetry.pb.h"
 #include "NodeDB.h"
 #include "ProtobufModule.h"
-#include "TelemetryHistory.h"
+#include "TelemetryStore.h"
 #include "detect/ScanI2C.h"
 #include "detect/ScanI2CConsumer.h"
 #include <OLEDDisplay.h>
@@ -44,25 +54,24 @@ class AirQualityTelemetryModule : private concurrency::OSThread,
         lastMeasurementPacket = nullptr;
         nodeStatusObserver.observe(&nodeStatus->onNewStatus);
         setIntervalFromNow(10 * 1000);
+        openHistory(); // safe here: fsInit() and setupSDCard() both run before setupModules()
     }
+
+    ~AirQualityTelemetryModule() { delete history; }
     virtual bool wantUIFrame() override;
 #if !HAS_SCREEN
     void drawFrame(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y);
 #else
     virtual void drawFrame(OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y) override;
 #endif
 
-    // Pure local-loop policy: the device reads at its own near-realtime cadence so an attached phone
-    // sees live values, independent of the on-air interval. Either consumer can drive the read - the
-    // offload keeps the loop alive when a backed-up phone queue would otherwise stall it. everRead
-    // (rather than a lastReadMs sentinel) marks the never-read state, so a read stamped at
-    // millis()==0 still honors the cadence.
+    // Local loop runs at its own cadence, independent of the on-air interval; either consumer can
+    // drive it. everRead, not a lastReadMs sentinel, marks the never-read state.
     static bool shouldReadSensors(bool everRead, uint32_t nowMs, uint32_t lastReadMs, uint32_t localIntervalMs,
                                   bool phoneQueueEmpty, bool meshPublishDue);
 
-    // Pure offload policy: the mesh takes a sample of the local loop's readings on its own interval,
-    // not every one of them. A power-saving SENSOR takes this path even with nothing left to send,
-    // because sendTelemetry() is also what arms its deep sleep.
+    // The mesh samples the loop on its own interval. A power-saving SENSOR takes this path even with
+    // nothing to send, because sendTelemetry() is what arms its deep sleep.
     static bool shouldSendToMesh(bool haveUnsentReading, bool meshDue, bool meshAllowed, bool powerSavingSensor);
 
   protected:
@@ -76,11 +85,7 @@ class AirQualityTelemetryModule : private concurrency::OSThread,
     */
     bool getAirQualityTelemetry(meshtastic_Telemetry *m);
     virtual meshtastic_MeshPacket *allocReply() override;
-    /**
-     * Publish the newest reading in history to the mesh or the phone. Does nothing if nothing has
-     * been read yet, or if this destination already had that reading.
-     * @return true if a packet was handed off to send
-     */
+    /// Publish the newest reading to the mesh or the phone, unless that destination already had it.
     bool sendTelemetry(NodeNum dest = NODENUM_BROADCAST, bool phoneOnly = false);
 
     virtual AdminMessageHandleResult handleAdminMessageForModule(const meshtastic_MeshPacket &mp,
@@ -89,6 +94,7 @@ class AirQualityTelemetryModule : private concurrency::OSThread,
     void i2cScanFinished(ScanI2C *i2cScanner);
 
   private:
+    void openHistory();
     /// Read every sensor once and push the result into history with the time it was taken.
     void captureReading();
     /// Wake any sleeping sensor. @return ms to wait for the slowest one, 0 if all are ready.
@@ -98,14 +104,13 @@ class AirQualityTelemetryModule : private concurrency::OSThread,
     bool firstTime = true;
     meshtastic_MeshPacket *lastMeasurementPacket;
 
-    // Cadence of the local device-to-phone loop, and the thread's own tick. Deliberately unrelated
-    // to air_quality_interval: that one paces what goes on air.
+    // Local device-to-phone cadence and the thread's tick; unrelated to air_quality_interval,
+    // which paces what goes on air.
     uint32_t localLoopIntervalMs = SECONDS_IN_MINUTE * 1000;
 
-    // What the local loop has measured, newest last. The offload publishes one of these readings
-    // rather than triggering a read of its own, so one sensor warm-up feeds the phone, the mesh, the
-    // screen and on-demand requests, and a packet is never restamped as fresher than it is.
-    TelemetryHistory<meshtastic_AirQualityMetrics, AIR_QUALITY_TELEMETRY_HISTORY_SIZE> history;
+    // The offload publishes one of these rather than reading again, so one warm-up feeds the phone,
+    // the mesh, the screen and on-demand requests. Never null once openHistory() has run.
+    TelemetryStore<meshtastic_AirQualityMetrics> *history = nullptr;
 
     uint32_t lastReadMs = 0; // monotonic millis() of the last read attempt
     bool everRead = false;   // false until the first read attempt, whatever its outcome