woz_uwb_facade.h
Public header for UWB facade: exposes Aliro DS-TWR responder lifecycle and range query; the CCC…
Overview
Public header for UWB facade: exposes Aliro DS-TWR responder lifecycle and range query; the CCC engine is bound and unbound via internal ursk and stop calls.
used by aliro_ranging.c cherry_ccc_shim.c uwb_selftest.c flight_recorder.c woz_uwb_facade.c
API
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).
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().
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.