woz_uwb_facade.h

Cstruct woz_uwb_aliro_cfg

Aliro UWB ranging parameters negotiated during M1-M4 handshake.

session_id

Aliro UWB session identifier (any non-zero value).

channel

UWB operating channel (5 or 9).

sync_code_index

SYNC/preamble code index (1..32).

slot_duration_rstu

Slot duration in RSTU units (1200 = 1 ms).

block_duration_ms

Ranging block repetition period in milliseconds.

slot_per_round

Number of slots per ranging round.

sts_index0

Starting STS (Scrambled Timestamp Sequence) index.

uwb_time_us

UWB_Time0 initiation reference in microseconds.

ursk

32-byte URSK (provisioned STS root key).

ranging_config

Serialized RangingConfiguration (CCC SaltedHash input), or NULL to use URSK fallback.

rc_len

RangingConfiguration length in bytes (typically 17).

Cstruct woz_uwb_range_integrity

Layer-2 evidence for a latched range, for a consumer that must fail closed.

Fint woz_uwb_bind_ursk(const uint8_t *ursk, size_t ursk_len)

Bind the CCC STS from the add-on-supplied plaintext URSK; returns 0 on success.

Fint woz_uwb_start_aliro(const struct woz_uwb_aliro_cfg *cfg)

Start the CCC DS-TWR responder bound to a live Aliro credential; returns 0 on success.

Fint woz_uwb_prewarm(uint8_t channel, uint8_t sync_code_index)

Pre-apply the expected session PHY (radio configured, TRX off, RX not armed) so the M4-time start skips the dwt_configure long pole when the negotiated params match.

Fvoid woz_uwb_stop(void)

Quiesce the radio and unbind the CCC STS shim.

Fbool woz_uwb_last_range_cm(int32_t *cm_out)

Latest distance in cm; true if a valid range has been seen.

Fbool woz_uwb_trusted_range_cm(int32_t *cm_out)

Latest distance in cm, gated by the range-integrity consensus (layer 4): true only when a valid range has been seen AND it is trusted (fira_session_range_trusted()). This is the accessor the unlock decision must use so a single unverified/spoofed block cannot drive an unlock; raw telemetry keeps using woz_uwb_last_range_cm(). Without CONFIG_WOZ_ALIRO there is no trust concept and this matches woz_uwb_last_range_cm().

Fbool woz_uwb_trusted_range_age_cm(int32_t *cm_out, int64_t *age_ms_out)

As woz_uwb_trusted_range_cm(), plus how long ago that range landed. For callers that must judge whether a range is still CURRENT rather than merely the most recent one seen -- a distance from two minutes ago says nothing about who is standing here now. Polling this beats registering a range listener to timestamp latches: there is only one listener slot, and an app that already owns it (the lock's approach loop) would otherwise be displaced.

Fuint32_t woz_uwb_range_generation(void)

Monotonic accepted-range epoch for post-challenge freshness checkpoints.

Fbool woz_uwb_trusted_range_after_cm(int32_t *cm_out, uint32_t after)

Trusted distance only when its accepted-range epoch is newer than after. This is the demand-driven presence seam: an old latch can never satisfy a challenge merely because it remains recent in wall-clock terms.

Fbool woz_uwb_trusted_range_after_checked_cm(int32_t *cm_out, uint32_t after, struct woz_uwb_range_integrity *ig_out)

As woz_uwb_trusted_range_after_cm(), plus the integrity evidence recorded with that latch. The plain accessor answers "how far", which is all an unlock decision needs; this one also answers "how well was that measured", which is what a caller has to know before signing the number into a statement someone else will believe. Without CONFIG_WOZ_ALIRO there is no evidence to report and ig_out reads back as a failed STS.

Fvoid woz_uwb_set_range_listener(void (*cb)(void))

Register a callback fired after each accepted range latch (NULL to clear), so the unlock seam can block on an event instead of polling. The callback runs on the UWB RX path — keep it to a task wake, nothing heavier. A no-op without CONFIG_WOZ_ALIRO.