aliro_approach.c File Reference

Kalman-filtered approach controller for predictive unlock. More...

#include "aliro_approach.h"
#include <string.h>

Include dependency graph for aliro_approach.c:

Functions
static void	kf_rebase (struct aliro_approach *ap, int64_t now_ms, int32_t cm)
	Reset the Kalman filter to a new state given a fresh measurement: clears rejection history, zeroes velocity, reinitializes covariance, and resets prediction state.
void	aliro_approach_defaults (struct aliro_approach_cfg *cfg)
	Initialize an approach configuration with factory defaults: unlock at 100 cm, relock at 250 cm, dwell times 2 s and 3 s, motor delay 500 ms, margin 250 ms, velocity floor 30 cm/s, predictive unlock enabled.
void	aliro_approach_init (struct aliro_approach *ap, const struct aliro_approach_cfg *cfg)
	Initialize an approach controller to locked state with zero velocity and no prediction in flight.
static enum aliro_approach_action	pred_abort (struct aliro_approach *ap)
	Record a predictive unlock abort and relock the door.
enum aliro_approach_action	aliro_approach_feed (struct aliro_approach *ap, int64_t now_ms, int32_t cm)
	Update the Kalman filter state with a new range measurement, compute estimated time-to-arrival (ETA) at the unlock radius, track presence via a median-filter window, and supervise predictive unlock (fire early when closing speed and ETA permit, abort if the phone stops or moves away).
void	aliro_approach_observe_departure (struct aliro_approach *ap, int64_t now_ms, int32_t cm)
	Supervise an active predictive unlock when no new measurement arrives this window.
enum aliro_approach_action	aliro_approach_tick (struct aliro_approach *ap, int64_t now_ms)
	Advance the approach state machine by one tick: handle predictive unlock abort on deadline, departure by silence when measurements stop after the phone leaves the relock threshold, and return the triggered action or HOLD if no action occurred.
enum aliro_approach_action	aliro_approach_gone (struct aliro_approach *ap)
	Reset the approach controller to locked state while preserving its configuration.
bool	aliro_approach_locked (const struct aliro_approach *ap)
	Return true if the door is locked, false if unlocked.
int32_t	aliro_approach_est_cm (const struct aliro_approach *ap)
	Return the current estimated distance in centimeters.
int32_t	aliro_approach_vel_cm_s (const struct aliro_approach *ap)
	Return the current velocity in centimeters per second (positive = approaching, negative = receding).
int32_t	aliro_approach_eta_ms (const struct aliro_approach *ap)
	Return the estimated time in milliseconds until approach completes (unlock reaches the door).

Detailed Description

Kalman-filtered approach controller for predictive unlock.

Tracks distance (cm), velocity (cm/s), and estimated time-to-arrival (ms) at the unlock radius. Supervises presence via median filtering of trusted ranges and fires predictive unlock when closing speed and ETA meet thresholds. Factory defaults: unlock 100 cm, relock 250 cm, dwell times 2 s and 3 s, motor delay 500 ms, margin 250 ms, velocity floor 30 cm/s, prediction enabled.

Function Documentation

aliro_approach_est_cm()

int32_t aliro_approach_est_cm

(

const struct aliro_approach *

ap

)

Return the current estimated distance in centimeters.

Returns -1 if the Kalman filter has not been initialized (no valid measurement yet); otherwise returns the rounded estimate.

aliro_approach_eta_ms()

int32_t aliro_approach_eta_ms

(

const struct aliro_approach *

ap

)

Return the estimated time in milliseconds until approach completes (unlock reaches the door).

Value is -1 if not yet computed, or the reader has already locked the door.

aliro_approach_feed()

enum aliro_approach_action aliro_approach_feed	(	struct aliro_approach *	ap,
		int64_t	now_ms,
		int32_t	cm
	)

Update the Kalman filter state with a new range measurement, compute estimated time-to-arrival (ETA) at the unlock radius, track presence via a median-filter window, and supervise predictive unlock (fire early when closing speed and ETA permit, abort if the phone stops or moves away).

Return the action code: UNLOCK_THRESHOLD (entered unlock zone), RELOCK_DEPART (exited relock zone), UNLOCK_PREDICT (fired a predictive unlock), or HOLD (no action).

aliro_approach_gone()

enum aliro_approach_action aliro_approach_gone

(

struct aliro_approach *

ap

)

Reset the approach controller to locked state while preserving its configuration.

Return RELOCK_DEPART if the door was unlocked before the reset, otherwise HOLD.

aliro_approach_init()

void aliro_approach_init	(	struct aliro_approach *	ap,
		const struct aliro_approach_cfg *	cfg
	)

Initialize an approach controller to locked state with zero velocity and no prediction in flight.

If cfg is NULL, load factory defaults; otherwise copy the provided configuration.

aliro_approach_observe_departure()

void aliro_approach_observe_departure	(	struct aliro_approach *	ap,
		int64_t	now_ms,
		int32_t	cm
	)

Supervise an active predictive unlock when no new measurement arrives this window.

Record a range for the DEPARTURE decision alone, trust gate or no trust gate.

If the prediction deadline has passed, abort and relock the door. Return HOLD otherwise.

aliro_approach_vel_cm_s()

int32_t aliro_approach_vel_cm_s

(

const struct aliro_approach *

ap

)

Return the current velocity in centimeters per second (positive = approaching, negative = receding).

Returns 0 if the Kalman filter has not been initialized.

pred_abort()

static enum aliro_approach_action pred_abort ( struct aliro_approach *  ap )

static

Record a predictive unlock abort and relock the door.

Called when prediction is active but the phone has stopped approaching or moved away.