/*
 * proxvec.h -- Proximity Vector Engine (kinematics layer, unified)
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 *
 * Pure logical engine between the hardware layer (bledsp) and the
 * display layer (radar_ui).  Consumes smoothed RSSI from bledsp's
 * unified device table (BLE + future WiFi sources), converts to
 * abstract grid coordinates, tracks velocity, and determines alarm
 * state via a finite-state machine per target.
 */
#ifndef PROXVEC_H
#define PROXVEC_H

#include <stdint.h>
#include "bledsp.h"

/* ------------------------------------------------------------------ */
/*  Constants                                                          */
/* ------------------------------------------------------------------ */

#define PROXVEC_MAX_TARGETS       BLE_DSP_MAX_DEVICES

/* Abstract grid size -- coordinates are mapped onto the LVGL canvas
 * by radar_ui.  Using a fixed grid keeps the kinematics independent
 * of the display resolution. */
#define PROXVEC_GRID_SIZE         240     /* abstract units          */

/* Path-loss model parameters (indoor, n ~= 2.5) */
#define PROXVEC_PATH_LOSS_N       25      /* fixed-point x10: 2.5    */
#define PROXVEC_TX_POWER_DEFAULT  40      /* assumed Tx power dBm x10 */

/* Alarm: target within this many grid units of center triggers alarm */
#define PROXVEC_ALARM_RADIUS      50

/* Stale timeout: drop target if not seen for this many ms */
#define PROXVEC_STALE_MS          5000

/* Velocity is in grid-units per update tick.
 * APPROACHING = moving toward center (negative radial velocity).
 * RECEDING    = moving away from center. */
typedef enum {
    TRACK_NEW         = 0,
    TRACK_APPROACHING,
    TRACK_STATIONARY,
    TRACK_RECEDING,
    TRACK_LOST
} track_state_t;

/* ------------------------------------------------------------------ */
/*  Target record (consumed by radar_ui)                               */
/* ------------------------------------------------------------------ */

typedef struct {
    uint8_t       mac[6];
    track_state_t state;
    int16_t       x;               /* grid coordinate  [0 .. GRID_SIZE) */
    int16_t       y;               /* grid coordinate  [0 .. GRID_SIZE) */
    int16_t       radius;          /* distance from center (grid units)  */
    int16_t       prev_radius;     /* previous tick's radius             */
    int16_t       velocity;        /* radial velocity (grid units/tick)  */
    uint8_t       intensity;       /* 0-255, mapped from smoothed RSSI  */
    uint8_t       alarm;           /* 1 = within ALARM_RADIUS           */
    uint8_t       age_ticks;       /* ticks since first detection       */
} proxvec_target_t;

/* ------------------------------------------------------------------ */
/*  Public API                                                         */
/* ------------------------------------------------------------------ */

/* Initialise the tracking engine. */
void proxvec_init(void);

/* Feed a batch of devices from bledsp.  Call once per scan cycle. */
void proxvec_update(const bledsp_device_t *devices, int count);

/* Copy active targets into caller-supplied buffer.
 * Returns the number of targets written. */
int  proxvec_get_targets(proxvec_target_t *out, int max);

/* Returns the count of targets currently in alarm state. */
int  proxvec_get_alarm_count(void);

/* Returns total targets being tracked (including non-alarm). */
int  proxvec_get_track_count(void);

/* Clear all targets and reset state machine. */
void proxvec_reset(void);

/* Adjust the alarm radius at runtime (grid units). */
void proxvec_set_alarm_radius(int16_t r);
int16_t proxvec_get_alarm_radius(void);

/* Shutdown: free any dynamic resources. */
void proxvec_shutdown(void);

#endif /* PROXVEC_H */