modules/woz_uwb/src/facade/woz_uwb_facade.c
asxeem/openaliro
Module

woz_uwb_facade.c

UWB facade: binds the CCC credential-based STS engine to the DW3000 radio, exposes Aliro DS-TWR…

modules/woz_uwb/src/facade/woz_uwb_facade.c8 documented symbols

Overview

UWB facade: binds the CCC credential-based STS engine to the DW3000 radio, exposes Aliro DS-TWR responder start/stop and range query, and manages platform dependencies (HFCLK boost, SPI init, callbacks).

depends on aliro_kdf.h ccc_shim.h flight_recorder.h woz_uwb_facade.h fira_session.h

API

Fstatic void woz_hfclk_ensure_128mhz(void)

modules/woz_uwb/src/facade/woz_uwb_facade.c:27

One-shot boost of the app-core HFCLK to 128 MHz for the DW3000 SPI bus. nRF5340-specific platform seam: the app core boots with HFCLK divided to 64 MHz. Other SoCs (e.g. ESP32-S3) clock their SPI controller independently, so this compiles to a no-op there. See docs/porting.md.

called by woz_uwb_bind_ursk, woz_uwb_prewarm, woz_uwb_start_aliro

Fint woz_uwb_bind_ursk(const uint8_t *ursk, size_t ursk_len)

modules/woz_uwb/src/facade/woz_uwb_facade.c:45

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

ursk
Pointer to the URSK bytes.
ursk_len
Length of the URSK.
returns
0 on success, -EINVAL if ursk is NULL.
calls woz_hfclk_ensure_128mhz

Fint woz_uwb_start_aliro(const struct woz_uwb_aliro_cfg *c)

modules/woz_uwb/src/facade/woz_uwb_facade.c:60

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

c
Configuration struct (channel, sync_code_index, ursk, ranging_config, sts_index0, slot_per_round).
returns
0 on success, -EINVAL if config is NULL or ursk is NULL, -EIO if radio initialization fails.
calls woz_hfclk_ensure_128mhz

Fint woz_uwb_prewarm(uint8_t channel, uint8_t sync_code_index)

modules/woz_uwb/src/facade/woz_uwb_facade.c:97

Pre-apply the expected session PHY so the M4-time start skips dwt_configure.

channel
UWB channel the upcoming session is expected to negotiate.
sync_code_index
Expected SYNC code index.
returns
0 on success; the M4 start recovers with a full configure on any failure.
calls woz_hfclk_ensure_128mhz

Fvoid woz_uwb_stop(void)

modules/woz_uwb/src/facade/woz_uwb_facade.c:106

Quiesce the radio and unbind the CCC STS shim.

Fbool woz_uwb_last_range_cm(int32_t *cm_out)

modules/woz_uwb/src/facade/woz_uwb_facade.c:120

Retrieve the last valid DS-TWR distance measurement in centimeters.

cm_out
Pointer to store the distance in cm.
returns
True if a valid range has been seen since initialization; false otherwise.

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

modules/woz_uwb/src/facade/woz_uwb_facade.c:138

Register a callback fired after each accepted DS-TWR range latch.

cb
Callback invoked on the UWB RX path (keep it to a task wake), or NULL to clear. Without CONFIG_WOZ_ALIRO there is no range latch to observe and this is a no-op.

Fbool woz_uwb_trusted_range_cm(int32_t *cm_out)

modules/woz_uwb/src/facade/woz_uwb_facade.c:147

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().