fira_session.h

Go to the documentation of this file.

 
#ifndef WOZ_UWB_FIRA_SESSION_H_
#define WOZ_UWB_FIRA_SESSION_H_
 
#include <stdbool.h>
#include <stdint.h>
 
bool fira_session_last_range(int32_t *cm_out, uint16_t *addr_out, uint8_t *nlos_out,
                             uint32_t *block_out, int64_t *age_ms_out);
 
#if defined(CONFIG_WOZ_ALIRO)
void fira_session_set_provisioned_ursk(const uint8_t *ursk);
 
const uint8_t *fira_session_get_ursk(void);
 
void fira_session_set_ccc_range_cm(int32_t cm, uint32_t block);
 
void fira_session_set_ccc_range_sts(int32_t driver_verdict, int16_t quality_index);
 
struct fira_range_integrity {
        bool sts_ok;         
        int16_t sts_quality; 
        uint8_t trust_level; 
};
 
bool fira_session_last_range_integrity(struct fira_range_integrity *out);
 
void fira_session_reset_ranges(void);
 
uint32_t fira_session_range_generation(void);
 
uint32_t fira_session_current_slot(void);
 
/* ── Range-integrity gate (anti-spoof / anti Ghost-Peak) ─────────────────────
 *
 * A DS-TWR distance is trustworthy only when it is (1) physically plausible,
 * (2) backed by a well-correlated STS, and (4) consistent with recent blocks.
 * (Layer 3, an Ipatov first-path check, was removed — untunable on this HW —
 * so the numbering keeps a gap.) Layers 1 and 4 are enforced in the range
 * store (fira_session_set_ccc_range_cm); layer 2 is a pure predicate the
 * responder RX path evaluates, since it owns the DW3000 diagnostics. Every
 * threshold below is a bring-up default — tune on the bench.
 *
 * Layer 2 is recorded rather than enforced here, on purpose, because its two
 * consumers want opposite failure modes. A door lock must not refuse to open
 * on a marginal block — a mis-tuned floor locks a human out of their house —
 * so it keeps the shadow behaviour and only drops blocks under
 * CONFIG_WOZ_RANGE_GATE_STRICT. A signed presence assertion is the opposite:
 * it exists to be believed by someone who was not there, so it must refuse to
 * state a distance it cannot vouch for. The store therefore carries the
 * verdict alongside the range and lets each consumer pick.
 */
 
/* Layer 1 — plausibility band. Below -NEG_TOL is physically impossible (an
 * early-first-path / Ghost-Peak spoof drives ToF sharply negative); above MAX
 * is outside any Aliro proximity envelope. A small negative is legitimate
 * point-blank calibration slop and reads as 0 cm rather than being dropped. */
#define FIRA_RANGE_NEG_TOL_CM 30   /* legit point-blank slop; drop beyond */
#define FIRA_RANGE_MAX_CM     3000 /* usable envelope (30 m); tune to radio */
 
bool fira_session_range_plausible(int32_t cm);
 
/* Layer 2 — STS quality floor. dwt_readstsquality() returns >=0 for good STS,
 * <0 for bad, and its signed index is "good" at >= ~60% of the STS length. A
 * spoofed early path cannot reproduce the scrambled sequence, so its STS
 * quality collapses. Raise MIN toward the 60%-of-length index to tighten. */
#define FIRA_STS_QUALITY_MIN 0 /* index floor; 0 = defer to driver verdict */
 
bool fira_session_sts_quality_ok(int32_t driver_verdict, int16_t quality_index);
 
/* Layer 4 — cross-block consensus. A single injected block cannot move an
 * unlock decision alone: a range is "trusted" only once K consecutive plausible
 * blocks agree to within SPREAD. This does not gate the latched last-range (the
 * shell/telemetry still track live values); it is the trust bit now wired into
 * the unlock path via woz_uwb_trusted_range_cm(), which surfaces a distance only
 * once trust is built. */
#define FIRA_RANGE_TRUST_K   3  /* consecutive agreeing blocks to trust */
#define FIRA_RANGE_SPREAD_CM 50 /* max block-to-block delta to stay agreed */
 
bool fira_session_range_trusted(void);
 
uint8_t fira_session_trust_level(void);
 
void fira_session_set_range_listener(void (*cb)(void));
#endif /* CONFIG_WOZ_ALIRO */
 
#endif /* WOZ_UWB_FIRA_SESSION_H_ */