Module wall_clock 

The device’s wall clock: what time it is, where that came from, and whether it is known at all.

A device of this class has a monotonic timer and, usually, nothing else. Wall-clock time arrives from outside — a GNSS fix, a battery-backed real-time clock, a host that was asked — and is held as an offset from the monotonic timer rather than as a counter of its own, so it costs nothing to maintain and cannot drift relative to everything else the device schedules.

Two things here are policy rather than mechanism, and both are deliberately in one place:

• Not knowing is a state. WallClockState::now returns None until something sets the clock. Callers must not substitute zero, a build timestamp, or any other plausible-looking value — a device that does not know the time must not display one.
• Sources outrank each other. WallClockState::apply holds the whole precedence rule, so no caller has to remember it and no two callers can disagree about it.

WallClockState is pure and testable on any host. The module-level statics behind the embassy feature are the single live instance the firmware shares.

Structs

WallClockState

The wall clock, as an offset from a monotonic millisecond timer.

Enums

TimeSource

Where a wall-clock reading came from.

Update

What WallClockState::apply did.

Constants

NOTABLE_STEP_SECS

How far the clock must move for the change to be worth telling anyone about, in seconds.

Functions

apply

Offer a reading, applying the precedence rule. See WallClockState::apply.

clear

Return the device to not knowing what time it is.

is_set

Whether the device knows what time it is.

local_hhmm

The local hour and minute, or None when the time is unknown.

millis_to_next_minute

Milliseconds until the next minute boundary, or None when the time is unknown.

now

The current time in Unix seconds, or None when the device does not know what time it is.

set_manual

Set the clock from a host or an operator.

set_tz

Set the time zone.

snapshot

The whole clock, for a caller that wants the reading, the zone, and the source without three separate critical sections.

tz_offset_min

Minutes east of UTC.