86 lines
3.5 KiB
C++
86 lines
3.5 KiB
C++
#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
|