Merge branch 'feat-additional-compensation' of https://github.com/jpirnay/crosspoint-reader into mybuild

lib/hal/HalClock.h

@@ -0,0 +1,85 @@
+#pragma once
+
+#include <cstdint>
+#include <ctime>
+
+/// Lightweight wall-clock facade.
+///
+/// The ESP32-C3 has no battery-backed RTC, so wall-clock time is lost on every
+/// deep-sleep / power cycle.  HalClock bridges this gap using three layers:
+///
+///  - **LP timer** (`esp_clk_rtc_time()`) — keeps running during deep sleep
+///    when `keepClockAlive` is enabled (GPIO13 stays HIGH).  Used to compute
+///    elapsed time and correct the stored epoch on wake.
+///  - **RTC memory** (`RTC_NOINIT_ATTR`) — survives deep sleep, lost on cold
+///    boot.  Stores the epoch + LP timer value captured before sleep.
+///  - **NVS** (flash key-value store) — survives power cycles.  Fallback when
+///    RTC memory is unavailable (cold boot).
+///
+/// Usage:
+///  1. On boot, call `restore()` to seed the system clock from the best
+///     available source (RTC memory + LP correction > NVS).
+///  2. After a successful NTP sync, call `syncNtp()`.
+///  3. Before entering deep sleep, call `saveBeforeSleep()`.
+///
+/// `now()` returns the best-effort epoch (0 if never synced).
+namespace HalClock {
+
+/// Perform an NTP sync (requires WiFi to be connected).  Starts SNTP,
+/// waits up to 5 seconds for completion, then captures the result.
+/// Returns true if the sync succeeded.
+bool syncNtp();
+
+/// Apply timezone/DST rules via the POSIX TZ string for the given setting.
+void applyTimezone(uint8_t timeZoneSetting);
+
+/// Call just before deep sleep.  Snapshots the current system time to RTC
+/// memory and NVS so it can be restored on wake / cold boot.  Pass true when
+/// the LP timer is kept alive during sleep.
+void saveBeforeSleep(bool keepLpAlive);
+
+/// Call on boot to seed the system clock from the best available stored
+/// value.  When RTC memory is valid (deep-sleep wake) and the LP timer was
+/// running, the restored time includes elapsed-time correction.  Falls back
+/// to NVS for cold boot (stale, but better than nothing).
+void restore();
+
+/// Returns the current best-effort wall-clock epoch, or 0 if the clock was
+/// never set.
+time_t now();
+
+/// True if the clock has been set at least once (NTP or restore).
+bool isSynced();
+
+/// Periodic callback (called from main loop) to compensate temperature-induced
+/// RTC drift while the device is awake.  Runs at a 10-minute interval.
+/// Computes the drift delta since the last baseline using the temperature
+/// model and nudges the system clock by only that delta (the kernel clock
+/// already advanced the raw amount).  Drift state is persisted to NVS only
+/// in saveBeforeSleep() to minimise flash wear.
+void updatePeriodic();
+
+/// True if the last restore was from a backup (not NTP) — i.e. the clock
+/// may have drifted.  Cleared on NTP sync.
+bool isApproximate();
+
+/// Returns the epoch of the last successful NTP sync (from NVS), or 0 if
+/// no sync has ever been recorded.
+time_t lastSyncTime();
+
+/// Format the current time for display.  Returns "--:--" if the clock was
+/// never synced, prefixes with "~" if approximate.
+/// When use24h is false, formats as "2:05pm" / "12:30am".
+/// Output is written to `buf` (must be at least 16 bytes).
+void formatTime(char* buf, size_t bufSize, bool use24h);
+
+/// Format the current time for log timestamps.  Returns "HH:MM:SS" if
+/// synced, or an empty string if not.
+void formatLogTime(char* buf, size_t bufSize);
+
+/// Tear down WiFi cleanly.  When skipNtpSync is false (default) and the
+/// clock is approximate, performs an opportunistic NTP sync before
+/// disconnecting — essentially free since we already have a connection.
+void wifiOff(bool skipNtpSync = false);
+
+}  // namespace HalClock