/*
 * bledsp.h -- Unified RF scanning + DSP hardware layer for proxalarm
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 *
 * Unified RF scanning layer that merges the old standalone radar.mod
 * (BLE hex grid scanner) and wifi.mod (adapter stub) into a single
 * source-agnostic device table.  Provides BLE LE scanning via BlueZ
 * HCI with rolling-average RSSI smoothing, and a WiFi RSSI poll
 * stub ready for a future WiFi driver (nl80211 / libnl).
 *
 * Memory note: on 64 MB RAM devices, this single module replaces
 * three separate binaries (radar.mod + wifi.mod + proxalarm.mod),
 * eliminating duplicate BLE HCI connections and reducing RSS .text
 * footprint by ~30 KB.
 *
 * Display: uses H2_LCD_WIDTH / H2_LCD_HEIGHT from h2_ui.h (320x240
 * on the H2; change those two defines for 320x320 panels).
 */
#ifndef BLE_DSP_H
#define BLE_DSP_H

#include <stdint.h>
#include <stddef.h>

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

#define BLE_DSP_MAX_DEVICES       32
#define BLE_DSP_RSSI_WINDOW       8       /* rolling-average samples  */
#define BLE_DSP_RSSI_FLOOR       -100     /* dBm: ignore anything weaker */
#define BLE_DSP_SCAN_INTERVAL_MS  1200    /* ms between scan sweeps    */
#define BLE_DSP_HCI_DEV            0       /* hci0                      */

/* RSSI thresholds (dBm) -- tunable at runtime via proxalarm UI */
#define BLE_DSP_THRESH_NEAR       -50     /* alarm zone               */
#define BLE_DSP_THRESH_MID        -70     /* tracking zone             */
#define BLE_DSP_THRESH_FAR        -85     /* detection zone            */

/* Signal source identifiers -- unified scanning supports multiple
 * RF sources simultaneously.  BLE is active; WiFi is a stub waiting
 * for a nl80211-based driver.  SIM is the fallback when no hardware
 * is available (all revisions without BLE/WiFi, or dev hosts). */
typedef enum {
    BLE_SRC_BLE  = 0,
    BLE_SRC_WIFI,          /* stub: bledsp_poll_wifi() returns 0 devices */
    BLE_SRC_SIM,           /* synthetic data for UI development / testing */
    BLE_SRC_COUNT
} bledsp_source_t;

/* ------------------------------------------------------------------ */
/*  Device record (fills the source -> proxvec interface)              */
/* ------------------------------------------------------------------ */

typedef struct {
    uint8_t      mac[6];
    int8_t       rssi_raw;          /* latest raw RSSI (dBm)           */
    int8_t       rssi_smoothed;     /* DSP-filtered RSSI (dBm)        */
    int8_t       rssi_delta;        /* change vs previous window (dB) */
    uint32_t     last_seen_ms;      /* monotonic timestamp            */
    uint8_t      active      : 1;  /* 1 = seen in last scan window   */
    uint8_t      source      : 2;  /* bledsp_source_t                */
    uint8_t      scan_count;        /* consecutive detections         */
} bledsp_device_t;

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

/* Open HCI, configure LE scan, allocate internal state.
 * Returns 0 on success, -1 on failure (falls back to sim mode). */
int  bledsp_init(void);

/* Run one scan cycle.  Non-blocking; returns immediately after
 * dispatching the HCI command or (in sim mode) generating data. */
int  bledsp_poll(void);

/* Look up a device by MAC.  Returns pointer into internal table
 * or NULL.  Valid until next bledsp_poll() call. */
const bledsp_device_t *bledsp_find(const uint8_t *mac);

/* Copy the full active device table into caller-supplied buffer.
 * Returns the number of active devices written (0 .. MAX). */
int  bledsp_get_devices(bledsp_device_t *out, int max);

/* Get the smoothed RSSI for a single MAC address.
 * Returns the smoothed value or BLE_DSP_RSSI_FLOOR if unknown. */
int16_t bledsp_get_smoothed_rssi(const uint8_t *mac);

/* Adjust the near-alarm RSSI threshold at runtime (dBm). */
void bledsp_set_near_threshold(int8_t dBm);
int8_t bledsp_get_near_threshold(void);

/* Get the active source mode (BLE_SRC_BLE, BLE_SRC_WIFI, or BLE_SRC_SIM). */
bledsp_source_t bledsp_get_source(void);

/* Cycle the active source.  Returns the new source.
 * Order: BLE -> WIFI -> BLE (SIM is auto-selected when HW fails). */
bledsp_source_t bledsp_cycle_source(void);

/* Check whether the backend is real BLE or simulation. */
int  bledsp_is_simulated(void);

/* Get a human-readable label for the current source mode.
 * Returns a static string: "BLE", "WIFI", or "SIM". */
const char *bledsp_source_label(void);

/* WiFi scanning stub.  When a WiFi driver becomes available,
 * implement this function to scan for nearby APs/stations via
 * nl80211 and populate the device table with source=BLE_SRC_WIFI.
 * Currently returns 0 (no devices found).  The caller (bledsp_poll)
 * already marks all devices inactive before calling this, so stale
 * WiFi entries will naturally expire.
 *
 * Return: number of devices added/updated (0 = none). */
int bledsp_poll_wifi(void);

/* Stop scanning, close HCI socket, free resources. */
void bledsp_shutdown(void);

#endif /* BLE_DSP_H */