/** * @file edge_processing.h * @brief ADR-039 Edge Intelligence — dual-core CSI processing pipeline. * * Core 0 (WiFi): Produces CSI frames into a lock-free SPSC ring buffer. * Core 1 (DSP): Consumes frames, runs signal processing, extracts vitals. * * Features: * - Biquad IIR bandpass filters for breathing (0.1-0.5 Hz) and heart rate (0.8-2.0 Hz) * - Phase unwrapping and Welford running statistics * - Top-K subcarrier selection by variance * - Presence detection with adaptive threshold calibration * - Vital signs: breathing rate, heart rate (zero-crossing BPM) * - Fall detection (phase acceleration exceeds threshold) * - Delta compression (XOR + RLE) for bandwidth reduction * - Multi-person vitals via subcarrier group clustering * - 32-byte vitals packet (magic 0xC5110002) for server-side parsing */ #ifndef EDGE_PROCESSING_H #define EDGE_PROCESSING_H #include #include #include "esp_err.h" /* ---- Magic numbers ---- */ #define EDGE_VITALS_MAGIC 0xC5110002 /**< Vitals packet magic. */ #define EDGE_COMPRESSED_MAGIC 0xC5110005 /**< Compressed frame magic (was 0xC5110003, reassigned for ADR-069). */ /* ---- Buffer sizes ---- */ #define EDGE_RING_SLOTS 16 /**< SPSC ring buffer slots (power of 2). */ #define EDGE_MAX_IQ_BYTES 1024 /**< Max I/Q payload per slot. */ #define EDGE_PHASE_HISTORY_LEN 256 /**< Phase history buffer depth. */ #define EDGE_TOP_K 8 /**< Top-K subcarriers to track. */ /** * Max subcarriers per frame the edge pipeline will process. * * Target-conditional since 2026-08-28. The original 128 was an ESP32-S3 * assumption: pre-HE chips report at most 128 CSI bins. ADR-110 onboarded the * ESP32-C6 to the *capture* path but not to this one, and a C6 associated to an * HE-capable AP delivers HE20 frames with 256 bins (iq_len = 512 bytes). * * `process_frame()` guards with `n_subcarriers > EDGE_MAX_SUBCARRIERS -> return`, * so on C6 every frame was rejected and the whole edge pipeline — vitals, * presence, fall detection, per-slot counting — silently did nothing. The Edge * DSP task started, logged its banner, and never processed a frame. Confirmed * on hardware: no edge_proc log past init and no vitals packet ever reaching * the sink. * * HE-capable parts get 256; pre-HE parts keep 128 so they don't pay ~3.5 KB of * .bss they can never use. CONFIG_SOC_WIFI_HE_SUPPORT is the same switch * csi_collector.c uses to pick its rx_ctrl layout. */ #if CONFIG_SOC_WIFI_HE_SUPPORT #define EDGE_MAX_SUBCARRIERS 256 /**< HE20 carries 256 CSI bins (C6/C5). */ #else #define EDGE_MAX_SUBCARRIERS 128 /**< Pre-HE parts (S3 etc). */ #endif /* ---- Measured sample-rate tracking ---- * * The connected-STA probe produces up to 50 CSI opportunities per second, * while contention and callback gating make the delivered cadence variable. * Temporal filters must follow measured time rather than a fixed frame-rate * assumption. The 60 Hz estimator ceiling leaves jitter headroom above the * qualified 50 Hz callback limit. A one-second frame-count window represents * bursty but valid WiFi arrivals more accurately than averaging only selected * inter-frame intervals. */ #define EDGE_SAMPLE_RATE_MIN_HZ 8.0f #define EDGE_SAMPLE_RATE_MAX_HZ 60.0f #define EDGE_SAMPLE_RATE_EMA_ALPHA 0.25f #define EDGE_SAMPLE_RATE_WINDOW_MIN_US 1000000U #define EDGE_SAMPLE_RATE_WINDOW_MAX_US 3000000U static inline float edge_sample_rate_window_update(float current_hz, uint32_t frame_intervals, uint32_t elapsed_us) { if (frame_intervals == 0 || elapsed_us < EDGE_SAMPLE_RATE_WINDOW_MIN_US || elapsed_us > EDGE_SAMPLE_RATE_WINDOW_MAX_US) { return current_hz; } float instant_hz = (float)frame_intervals * 1000000.0f / (float)elapsed_us; if (instant_hz < EDGE_SAMPLE_RATE_MIN_HZ) instant_hz = EDGE_SAMPLE_RATE_MIN_HZ; if (instant_hz > EDGE_SAMPLE_RATE_MAX_HZ) instant_hz = EDGE_SAMPLE_RATE_MAX_HZ; float next_hz = current_hz + EDGE_SAMPLE_RATE_EMA_ALPHA * (instant_hz - current_hz); if (next_hz < EDGE_SAMPLE_RATE_MIN_HZ) return EDGE_SAMPLE_RATE_MIN_HZ; if (next_hz > EDGE_SAMPLE_RATE_MAX_HZ) return EDGE_SAMPLE_RATE_MAX_HZ; return next_hz; } /* ---- Multi-person ---- */ #define EDGE_MAX_PERSONS 4 /**< Max simultaneous persons. */ /** * Enforce the wire-level occupancy invariant. * * A subcarrier slot estimate is supporting evidence only. It cannot assert an * occupant when the independently debounced presence gate is false. Keeping * this helper in the public firmware header lets host tests exercise the exact * function used by the device build. */ static inline uint8_t edge_evidence_person_count(bool presence, uint8_t active_count) { if (!presence) return 0; return active_count > EDGE_MAX_PERSONS ? EDGE_MAX_PERSONS : active_count; } /* ---- Multi-person counting gates (issue #998) ---- * * Over-counting root cause: the multi-person path used to split the top-K * subcarriers into EDGE_MAX_PERSONS groups and mark EVERY group active, * so one body's multipath always reported the full EDGE_MAX_PERSONS. These * gates promote a subcarrier group to a real "person" only when it carries * genuine, distinct, persistent energy: * * 1. Energy gate — a group's phase variance must exceed a fraction of the * strongest group's variance, else it is multipath/noise. * 2. Spatial dedup — two groups whose representative subcarriers sit within * EDGE_PERSON_MIN_SC_SEP of each other are the same body * (adjacent subcarriers see correlated reflections), so * the weaker one is merged away. * 3. Persistence — a candidate count must hold for EDGE_PERSON_PERSIST_FRAMES * consecutive decisions before it is emitted, so a single * noisy frame cannot promote a phantom person. * * These are robustness gates on the existing heuristic, not a calibrated * occupancy model — true count accuracy vs ground truth remains data-gated. */ #define EDGE_PERSON_MIN_ENERGY_RATIO 0.35f /**< Group var must be >= this * max group var to count. */ #define EDGE_PERSON_MIN_SC_SEP 4 /**< Min subcarrier separation between distinct persons. */ #define EDGE_PERSON_PERSIST_FRAMES 3 /**< Consecutive decisions a count must hold before emit. */ /* ---- Calibration ---- */ #define EDGE_CALIB_FRAMES 1200 /**< Frames for adaptive calibration (~60s at 20 Hz). */ #define EDGE_CALIB_SIGMA_MULT 3.0f /**< Threshold = mean + 3*sigma of ambient. */ /* ---- Fall detection ---- */ #define EDGE_FALL_COOLDOWN_MS 5000 /**< Minimum ms between fall alerts (debounce). */ #define EDGE_FALL_CONSEC_MIN 3 /**< Consecutive frames above threshold to trigger. */ /* ---- Presence flag hysteresis + debounce (issue #996) ---- * * Flicker root cause: the presence flag was a single-threshold compare on a * noisy presence_score (observed 2.6-26.7 frame-to-frame for one stationary * person), so the boolean chattered at the boundary even while the score * clearly indicated a person. Fix: Schmitt-trigger hysteresis plus a clear * debounce. * * - Assert presence when score > threshold (enter immediately). * - Hold presence while score >= threshold * HYST_RATIO (no flicker in the * gap band). * - Clear presence only after the score stays below the low threshold for * EDGE_PRESENCE_CLEAR_FRAMES consecutive frames (genuine departure). * * HYST_RATIO < 1.0 sets the low threshold below the high threshold; a wider gap * (smaller ratio) is more flicker-immune but slower to clear on real exit. The * exact ratio that best matches a given room's score scale remains an on-device * tuning parameter — this removes the logic bug (no hysteresis at all). */ #define EDGE_PRESENCE_HYST_RATIO 0.5f /**< Low thresh = HYST_RATIO * high thresh. */ #define EDGE_PRESENCE_CLEAR_FRAMES 5 /**< Frames below low thresh before clearing. */ /* ---- DSP task tuning ---- */ #define EDGE_BATCH_LIMIT 4 /**< Max frames per batch before longer yield. */ /* ---- SPSC ring buffer slot ---- */ typedef struct { uint8_t iq_data[EDGE_MAX_IQ_BYTES]; /**< Raw I/Q bytes from CSI callback. */ uint16_t iq_len; /**< Actual I/Q data length. */ int8_t rssi; /**< RSSI from rx_ctrl. */ uint8_t channel; /**< WiFi channel. */ uint32_t timestamp_us; /**< Microsecond timestamp. */ } edge_ring_slot_t; /* ---- SPSC ring buffer ---- */ typedef struct { edge_ring_slot_t slots[EDGE_RING_SLOTS]; volatile uint32_t head; /**< Written by producer (Core 0). */ volatile uint32_t tail; /**< Written by consumer (Core 1). */ } edge_ring_buf_t; /* ---- Biquad IIR filter state ---- */ typedef struct { float b0, b1, b2; /**< Numerator coefficients. */ float a1, a2; /**< Denominator coefficients (a0 = 1). */ float x1, x2; /**< Input delay line. */ float y1, y2; /**< Output delay line. */ } edge_biquad_t; /* ---- Welford running statistics ---- */ typedef struct { double mean; double m2; uint32_t count; } edge_welford_t; /* ---- Per-person vitals state (multi-person mode) ---- */ typedef struct { float phase_history[EDGE_PHASE_HISTORY_LEN]; uint16_t history_len; uint16_t history_idx; float breathing_bpm; float heartrate_bpm; uint8_t subcarrier_idx; /**< Which subcarrier group this person tracks. */ bool active; } edge_person_vitals_t; /* ---- Vitals packet (32 bytes, wire format) ---- */ typedef struct __attribute__((packed)) { uint32_t magic; /**< EDGE_VITALS_MAGIC = 0xC5110002. */ uint8_t node_id; /**< ESP32 node identifier. */ uint8_t flags; /**< Bit0=presence, Bit1=fall, Bit2=motion. */ uint16_t breathing_rate; /**< BPM * 100 (fixed-point). */ uint32_t heartrate; /**< BPM * 10000 (fixed-point). */ int8_t rssi; /**< Latest RSSI. */ uint8_t n_persons; /**< Number of detected persons (multi-person). */ uint8_t reserved[2]; float motion_energy; /**< Phase variance / motion metric. */ float presence_score; /**< Presence detection score. */ uint32_t timestamp_ms; /**< Milliseconds since boot. */ uint32_t reserved2; /**< Reserved for future use. */ } edge_vitals_pkt_t; _Static_assert(sizeof(edge_vitals_pkt_t) == 32, "vitals packet must be 32 bytes"); /* ---- ADR-069: CSI Feature Vector packet (48 bytes, wire format) ---- */ #define EDGE_FEATURE_MAGIC 0xC5110003 /**< Feature vector packet magic. */ typedef struct __attribute__((packed)) { uint32_t magic; /**< EDGE_FEATURE_MAGIC = 0xC5110003. */ uint8_t node_id; /**< ESP32 node identifier. */ uint8_t reserved; /**< Alignment padding. */ uint16_t seq; /**< Sequence number. */ int64_t timestamp_us; /**< Microseconds since boot. */ float features[8]; /**< 8-dim normalized feature vector. */ } edge_feature_pkt_t; _Static_assert(sizeof(edge_feature_pkt_t) == 48, "feature packet must be 48 bytes"); /* ---- ADR-063: Fused vitals packet (48 bytes, wire format) ---- */ #define EDGE_FUSED_MAGIC 0xC5110004 /**< Fused vitals packet magic. */ typedef struct __attribute__((packed)) { /* First 32 bytes match edge_vitals_pkt_t layout */ uint32_t magic; /**< EDGE_FUSED_MAGIC = 0xC5110004. */ uint8_t node_id; uint8_t flags; /**< Bit0=presence, Bit1=fall, Bit2=motion, Bit3=mmwave_present. */ uint16_t breathing_rate; /**< Fused BPM * 100 (CSI + mmWave Kalman). */ uint32_t heartrate; /**< Fused BPM * 10000. */ int8_t rssi; uint8_t n_persons; uint8_t mmwave_type; /**< mmwave_type_t enum. */ uint8_t fusion_confidence; /**< 0-100 fusion quality score. */ float motion_energy; float presence_score; uint32_t timestamp_ms; /* mmWave extension (16 bytes) */ float mmwave_hr_bpm; /**< Raw mmWave heart rate. */ float mmwave_br_bpm; /**< Raw mmWave breathing rate. */ float mmwave_distance;/**< Distance to nearest target (cm). */ uint8_t mmwave_targets; /**< Target count from mmWave. */ uint8_t mmwave_confidence; /**< mmWave signal quality 0-100. */ uint16_t reserved3; uint32_t reserved4; /**< Pad to 48 bytes for alignment. */ } edge_fused_vitals_pkt_t; _Static_assert(sizeof(edge_fused_vitals_pkt_t) == 48, "fused vitals must be 48 bytes"); /* ---- Edge configuration (from NVS) ---- */ typedef struct { uint8_t tier; /**< Processing tier: 0=raw, 1=basic, 2=full. */ float presence_thresh;/**< Presence detection threshold (0 = auto-calibrate). */ float fall_thresh; /**< Fall detection threshold (phase accel, rad/s^2). */ uint16_t vital_window; /**< Phase history window for BPM estimation. */ uint16_t vital_interval_ms; /**< Vitals packet send interval in ms. */ uint8_t top_k_count; /**< Number of top subcarriers to track. */ uint8_t power_duty; /**< Power duty cycle percentage (10-100). */ } edge_config_t; /** * Initialize the edge processing pipeline. * Creates the SPSC ring buffer and starts the DSP task on Core 1. * * @param cfg Edge configuration (from NVS or defaults). * @return ESP_OK on success. */ esp_err_t edge_processing_init(const edge_config_t *cfg); /** * Enqueue a CSI frame from the WiFi callback (Core 0). * Lock-free SPSC push — safe to call from ISR context. * * @param iq_data Raw I/Q data from wifi_csi_info_t.buf. * @param iq_len Length of I/Q data in bytes. * @param rssi RSSI from rx_ctrl. * @param channel WiFi channel number. * @return true if enqueued, false if ring buffer is full (frame dropped). */ bool edge_enqueue_csi(const uint8_t *iq_data, uint16_t iq_len, int8_t rssi, uint8_t channel); /** * Get the latest vitals packet (thread-safe copy). * * @param pkt Output vitals packet. * @return true if valid vitals data is available. */ bool edge_get_vitals(edge_vitals_pkt_t *pkt); /** * Return the timestamp-derived CSI cadence used to design temporal filters. * This is diagnostic evidence, not the raw callback or network delivery rate. */ float edge_get_sample_rate_hz(void); /** * Get multi-person vitals array. * * @param persons Output array (must be EDGE_MAX_PERSONS elements). * @param n_active Output: number of active persons. */ void edge_get_multi_person(edge_person_vitals_t *persons, uint8_t *n_active); /** * Get pointer to the phase history ring buffer and its state. * Used by WASM runtime (ADR-040) to expose phase history to modules. * * @param out_buf Output: pointer to phase history array. * @param out_len Output: number of valid entries. * @param out_idx Output: current write index. */ void edge_get_phase_history(const float **out_buf, uint16_t *out_len, uint16_t *out_idx); /** * Get per-subcarrier Welford variance array. * Used by WASM runtime (ADR-040) to expose variances to modules. * * @param out_variances Output array (must be EDGE_MAX_SUBCARRIERS elements). * @param n_subcarriers Number of subcarriers to fill. */ void edge_get_variances(float *out_variances, uint16_t n_subcarriers); #endif /* EDGE_PROCESSING_H */