aliro_approach.h
Overview
@file aliro_approach.h Configuration and state for approach detection and predictive unlock: unlock/relock thresholds in centimeters, sample-count dwell times, motor retraction time, scheduling margin, minimum closing speed, and a flag to enable or disable predictive ToA unlock.
used by aliro_approach.c
API
Cstruct aliro_approach_cfg
Configuration for approach detection: unlock_cm (presence radius and ETA target), relock_cm (departure threshold), near_dwell/far_dwell (sample counts to unlock/relock), motor_ms (bolt retraction time), margin_ms (scheduling slack, >= 192 ms to avoid missing discrete samples), vmin_cm_s (min closing speed to arm prediction), predict_en (false disables prediction and leaves presence path unchanged; also false whenever RSSI power gate is active).
Cstruct aliro_approach
State machine and Kalman filter for approach detection and predictive unlock. locked: bolt mirror state. win/wlen/wpos: median filter for distance. near_dwell/far_dwell: hysteresis counters. kf_init/accepted/rejects/last_ms/d/v/p00/p01/p11: constant-velocity Kalman filter (distance cm, velocity cm/s; negative velocity = closing). pred_dwell/pred_open/pred_deadline_ms/eta_ms: predictive unlock path (fires when closing speed >= vmin_cm_s and ETA to unlock_cm is within motor_ms + margin_ms).
##define ALIRO_APPROACH_MEDIAN_N 5
Cenum aliro_approach_action
Fvoid aliro_approach_defaults(struct aliro_approach_cfg *cfg)
Fvoid aliro_approach_init(struct aliro_approach *ap, const struct aliro_approach_cfg *cfg)
Fenum aliro_approach_action aliro_approach_feed(struct aliro_approach *ap, int64_t now_ms, int32_t cm)
Fvoid aliro_approach_observe_departure(struct aliro_approach *ap, int64_t now_ms, int32_t cm)
Record a range for the DEPARTURE decision alone, trust gate or no trust gate. Ranges beyond relock_cm are precisely the ones the range-integrity consensus declines to vouch for, so a walk-away can never satisfy a "seen beyond relock_cm" condition through aliro_approach_feed(). Measured 2026-08-02: the trace showed 252 cm then 309 cm as the credential left, while the controller had last been FED 210 cm, and both the silence rule and far_dwell refused -- correctly, on the data they had. Using an unvouched range here is safe in the one direction that matters. The trust gate exists to stop a forged NEAR range opening a door; a forged FAR range can only CLOSE one, and an attacker gains nothing by locking a lock. So departure may read what the radio saw, while the unlock decision keeps requiring what the radio can vouch for. Ignores anything nearer than relock_cm, which is what keeps the asymmetry honest: an unvouched range can cause a relock and can never prevent or delay one. Feed it only FRESH ranges -- the caller's generation epoch says which -- or the silence in aliro_approach_tick() never accumulates.