onlyn00bs-badge

clock.h (3815B)

---

 #pragma once
 #include <Arduino.h>
 #include <Preferences.h>
 #include "config.h"
 
 // ─────────────────────────────────────────────────────────────────────────
 //  Soft real-time clock.
 //
 //  The FireBeetle 2 ESP32-E badge board has no RTC, so we seed wall-clock time from the
 //  phone over BLE during provisioning, then free-run off millis(). To survive
 //  reboots without re-syncing, we checkpoint the current epoch to NVS every
 //  CLOCK_PERSIST_MS and resume from there on boot (downtime isn't counted —
 //  fine for a badge that runs continuously through a con).
 //
 //  If never synced, now() returns 0 and synced() is false → the report labels
 //  timestamps as relative rather than wall-clock.
 //
 //  A brownout reset means we were dark for an unknown span, so the resumed epoch is
 //  skewed by that downtime. setup() then calls mark_stale(): synced() goes false
 //  (report falls back to relative) and stale() drives a "re-sync" nudge, until a
 //  fresh BLE sync (OPTIONS → Provisioning Mode → hosted page) restores trust. The stale
 //  flag is persisted, so a later clean power-cycle can't silently un-stale it.
 // ─────────────────────────────────────────────────────────────────────────
 class SoftClock {
 public:
   void begin() {
     _p.begin("clock", false);
     _base_epoch = _p.getUInt("epoch", 0);
     _stale = _p.getUChar("stale", 0) != 0;
     _base_ms = millis();
     _last_persist = millis();
   }
 
   // "synced" = we hold a wall-clock we TRUST. False if never seeded, OR if marked
   // stale (e.g. resumed-from-NVS after a brownout, when the badge was dark for an
   // unknown span) — callers then fall back to relative time. A BLE re-sync restores it.
   bool synced() const { return _base_epoch != 0 && !_stale; }
 
   // Epoch is present but no longer trustworthy (downtime-skewed). Drives the nudge.
   bool stale() const { return _base_epoch != 0 && _stale; }
 
   uint32_t now() const {
     if (!_base_epoch) return 0;
     return _base_epoch + (millis() - _base_ms) / 1000;
   }
 
   // Called from the BLE time characteristic — a fresh sync restores trust.
   void set(uint32_t epoch) {
     _base_epoch = epoch;
     _base_ms = millis();
     _stale = false;
     _p.putUInt("epoch", epoch);
     _p.putUChar("stale", 0);
   }
 
   // Mark the persisted epoch untrusted. Persisted so it survives further reboots
   // until a re-sync clears it — a clean power-cycle after a brownout must not
   // silently "un-stale" a clock that's still skewed by the dark period.
   void mark_stale() {
     if (!_base_epoch || _stale) return;
     _stale = true;
     _p.putUChar("stale", 1);
   }
 
   // Factory reset: wipe the persisted epoch + stale flag. The clock lives in its OWN NVS
   // namespace ("clock"), so main.cpp's prefs.clear() on the "badge" namespace does NOT
   // reach it — without this a "wiped" badge still carries the previous owner's wall clock.
   // Caller is expected to restart immediately; the in-RAM state is reset too regardless.
   void factory_clear() {
     _p.clear();
     _base_epoch = 0;
     _base_ms = millis();
     _stale = false;
   }
 
   // Call often; checkpoints to NVS at most once per CLOCK_PERSIST_MS.
   void tick() {
     if (!_base_epoch) return;
     if (millis() - _last_persist >= CLOCK_PERSIST_MS) {
       _last_persist = millis();
       _p.putUInt("epoch", now());
     }
   }
 
 private:
   Preferences _p;
   uint32_t _base_epoch = 0;
   uint32_t _base_ms = 0;
   uint32_t _last_persist = 0;
   bool     _stale = false;       // epoch present but downtime-skewed → untrusted
 };