Signal Intelligence Modules -- WiFi-DensePose Edge Intelligence

Real-time WiFi signal analysis and enhancement running directly on the ESP32 chip. These modules clean, compress, and extract features from raw WiFi channel data so that higher-level modules (health, security, etc.) get better input.

Overview

How Signal Processing Fits In

The signal intelligence modules form a processing pipeline between raw CSI data and application-level modules:

  Raw CSI from WiFi chipset (Tier 0-2 firmware DSP)
       |
       v
  +---------------------+     +---------------------+
  | Coherence Gate       | --> | Sparse Recovery      |
  | Reject noisy frames, |     | Fill in dropped      |
  | gate quality levels  |     | subcarriers via ISTA  |
  +---------------------+     +---------------------+
       |                              |
       v                              v
  +---------------------+     +---------------------+
  | Flash Attention      |     | Temporal Compress    |
  | Focus on informative |     | Store CSI history    |
  | subcarrier groups    |     | at 3 quality tiers   |
  +---------------------+     +---------------------+
       |                              |
       v                              v
  +---------------------+     +---------------------+
  | Min-Cut Person Match |     | Optimal Transport    |
  | Track person IDs     |     | Detect subtle motion |
  | across frames        |     | via distribution     |
  +---------------------+     +---------------------+
       |                              |
       v                              v
  Application modules: Health, Security, Smart Building, etc.

The Coherence Gate acts as a quality filter at the top of the pipeline. Frames that pass the gate feed into the Sparse Recovery module (if subcarrier dropout is detected) and then into downstream analysis. Flash Attention identifies which spatial regions carry the most signal, while Temporal Compress maintains an efficient rolling history. Min-Cut Person Match and Optimal Transport extract higher-level features (person identity and motion) that application modules consume.

Shared Utilities (vendor_common.rs)

All signal intelligence modules share these utilities from vendor_common.rs:

Modules

Flash Attention (sig_flash_attention.rs)

What it does: Focuses processing on the WiFi channels that carry the most useful information -- ignores noise. Divides 32 subcarriers into 8 groups and computes attention weights showing where signal activity is concentrated.

Algorithm: Tiled attention (Q*K/sqrt(d)) over 8 subcarrier groups with softmax normalization and Shannon entropy tracking.

1. Compute group means: Q = current phase per group, K = previous phase per group, V = amplitude per group
2. Score each group: score[g] = Q[g] * K[g] / sqrt(8)
3. Softmax normalization (numerically stable: subtract max before exp)
4. Track entropy H = -sum(p * ln(p)) via EMA smoothing

Low entropy means activity is focused in one spatial zone (a Fresnel region); high entropy means activity is spread uniformly.

Public API

pub struct FlashAttention { /* ... */ }

impl FlashAttention {
    pub const fn new() -> Self;
    pub fn process_frame(&mut self, phases: &[f32], amplitudes: &[f32]) -> &[(i32, f32)];
    pub fn weights() -> &[f32; 8];       // Current attention weights per group
    pub fn entropy() -> f32;             // EMA-smoothed entropy [0, ln(8)]
    pub fn peak_group() -> usize;        // Group index with highest weight
    pub fn centroid() -> f32;            // Weighted centroid position [0, 7]
    pub fn frame_count() -> u32;
    pub fn reset(&mut self);
}

Events

Configuration

Tutorial: Understanding Attention Weights

The 8 attention weights sum to 1.0. When a person stands in a particular area of the room, the WiFi signal changes most in the subcarrier group(s) whose Fresnel zones intersect that area.

• All weights near 0.125 (= 1/8): Uniform attention. No localized activity -- either an empty room or whole-body motion affecting all subcarriers equally.
• One weight near 1.0, others near 0.0: Highly focused. Activity concentrated in one spatial zone. The peak_group index tells you which zone.
• Two adjacent groups elevated: Activity at the boundary between two spatial zones, or a person moving between them.
• Entropy below 1.0: Strong spatial focus. Good for zone-level localization.
• Entropy above 1.8: Nearly uniform. Hard to localize activity.

The centroid value (0.0 to 7.0) gives a weighted average position. Tracking centroid over time reveals motion direction across the room.

Coherence Gate (sig_coherence_gate.rs)

What it does: Decides whether each incoming CSI frame is trustworthy enough to use for sensing, or should be discarded. Uses the statistical consistency of phase changes across subcarriers to measure signal quality.

Algorithm: Per-subcarrier phase deltas form unit phasors (cos + i*sin). The magnitude of the mean phasor is the coherence score [0,1]. Welford online statistics track mean/variance for Z-score computation. A hysteresis state machine prevents rapid oscillation between states.

State transitions:

• Accept -> PredictOnly: 5 consecutive frames below LOW_THRESHOLD (0.40)
• PredictOnly -> Reject: single frame below threshold
• Reject/PredictOnly -> Accept: 10 consecutive frames above HIGH_THRESHOLD (0.75)
• Any -> Recalibrate: running variance exceeds 4x the initial snapshot

Public API

pub struct CoherenceGate { /* ... */ }

impl CoherenceGate {
    pub const fn new() -> Self;
    pub fn process_frame(&mut self, phases: &[f32]) -> &[(i32, f32)];
    pub fn gate() -> GateDecision;       // Accept/PredictOnly/Reject/Recalibrate
    pub fn coherence() -> f32;           // Last coherence score [0, 1]
    pub fn zscore() -> f32;              // Z-score of last coherence
    pub fn variance() -> f32;            // Running variance of coherence
    pub fn frame_count() -> u32;
    pub fn reset(&mut self);
}

pub enum GateDecision { Accept, PredictOnly, Reject, Recalibrate }

Events

Configuration

Tutorial: Using the Coherence Gate

The coherence gate protects downstream modules from processing garbage data. In practice:

1. Accept (value=2): Frame is clean. Use it for all sensing tasks (vitals, presence, gestures).
2. PredictOnly (value=1): Frame quality is marginal. Use cached predictions from previous frames; do not update models.
3. Reject (value=0): Frame is too noisy. Skip entirely. Do not feed to any learning module.
4. Recalibrate (value=-1): The environment has changed fundamentally (furniture moved, new AP, door opened). Reset baselines and re-learn.

Common causes of low coherence:

• Microwave oven running (2.4 GHz interference)
• Multiple people walking in different directions (phase cancellation)
• Hardware glitch (intermittent antenna contact)

Temporal Compress (sig_temporal_compress.rs)

What it does: Maintains a rolling history of up to 512 CSI snapshots in compressed form. Recent data is stored at high precision; older data is progressively compressed to save memory while retaining long-term trends.

Algorithm: Three-tier quantization with automatic demotion at age boundaries.

At 20 Hz, the buffer stores approximately:

• Hot: 3.2 seconds of high-fidelity data
• Warm: 9.6 seconds of medium-fidelity data
• Cold: 12.8 seconds of low-fidelity data
• Total: ~25.6 seconds, or longer at lower frame rates

Each snapshot stores 8 phase + 8 amplitude values (group means), plus a scale factor and tier tag.

Public API

pub struct TemporalCompressor { /* ... */ }

impl TemporalCompressor {
    pub const fn new() -> Self;
    pub fn push_frame(&mut self, phases: &[f32], amps: &[f32], ts_ms: u32) -> &[(i32, f32)];
    pub fn on_timer() -> &[(i32, f32)];
    pub fn get_snapshot(age: usize) -> Option<[f32; 16]>;  // Decompressed 8 phase + 8 amp
    pub fn compression_ratio() -> f32;
    pub fn frame_rate() -> f32;
    pub fn total_written() -> u32;
    pub fn occupied() -> usize;
}

Events

Configuration

Sparse Recovery (sig_sparse_recovery.rs)

What it does: When WiFi hardware drops some subcarrier measurements (nulls/zeros due to deep fades, firmware glitches, or multipath nulls), this module reconstructs the missing values using mathematical optimization.

Algorithm: Iterative Shrinkage-Thresholding Algorithm (ISTA) -- an L1-minimizing sparse recovery method.

x_{k+1} = soft_threshold(x_k + step * A^T * (b - A*x_k), lambda)

where:

• A is a tridiagonal correlation model (diagonal + immediate neighbors, 96 f32s instead of full 32x32=1024)
• b is the observed (non-null) subcarrier values
• soft_threshold(x, t) = sign(x) * max(|x| - t, 0) promotes sparsity
• Maximum 10 iterations per frame

The correlation model is learned online from valid frames using EMA-blended products.

Public API

pub struct SparseRecovery { /* ... */ }

impl SparseRecovery {
    pub const fn new() -> Self;
    pub fn process_frame(&mut self, amplitudes: &mut [f32]) -> &[(i32, f32)];
    pub fn dropout_rate() -> f32;           // Fraction of null subcarriers
    pub fn last_residual_norm() -> f32;     // L2 residual from last recovery
    pub fn last_recovered_count() -> u32;   // How many subcarriers were recovered
    pub fn is_initialized() -> bool;        // Whether correlation model is ready
}

Note: process_frame modifies amplitudes in place -- null subcarriers are overwritten with recovered values.

Events

Configuration

Tutorial: When Recovery Kicks In

1. The module needs at least 10 fully valid frames to initialize the correlation model (is_initialized() == true).
2. Recovery only triggers when dropout exceeds 10% (e.g., 4+ of 32 subcarriers are null).
3. Below 10%, the nulls are too sparse to warrant recovery overhead.
4. The tridiagonal correlation model exploits the fact that adjacent WiFi subcarriers are highly correlated. A null at subcarrier 15 can be estimated from subcarriers 14 and 16.
5. Monitor RECOVERY_ERROR -- a rising residual suggests the correlation model is stale and the environment has changed.

Min-Cut Person Match (sig_mincut_person_match.rs)

What it does: Maintains stable identity labels for up to 4 people in the sensing area. When people move around, their WiFi signatures change position -- this module tracks which signature belongs to which person across consecutive frames.

Algorithm: Inspired by ruvector-mincut (DynamicPersonMatcher). Each frame:

1. Feature extraction: For each detected person, extract the top-8 subcarrier variances (sorted descending) from their spatial region. This produces an 8D signature vector.
2. Cost matrix: Compute L2 distances between all current features and all stored signatures.
3. Greedy assignment: Pick the minimum-cost (detection, slot) pair, mark both as used, repeat. Like a simplified Hungarian algorithm, optimal for max 4 persons.
4. Signature update: Blend new features into stored signatures via EMA (alpha=0.15).
5. Timeout: Release slots after 100 frames of absence.

Public API

pub struct PersonMatcher { /* ... */ }

impl PersonMatcher {
    pub const fn new() -> Self;
    pub fn process_frame(&mut self, amplitudes: &[f32], variances: &[f32], n_persons: usize) -> &[(i32, f32)];
    pub fn active_persons() -> u8;
    pub fn total_swaps() -> u32;
    pub fn is_person_stable(slot: usize) -> bool;
    pub fn person_signature(slot: usize) -> Option<&[f32; 8]>;
}

Events

Configuration

Optimal Transport (sig_optimal_transport.rs)

What it does: Detects subtle motion that traditional variance-based detectors miss. Computes how much the overall shape of the WiFi signal distribution changes between frames, even when the total power stays constant.

Algorithm: Sliced Wasserstein distance -- a computationally efficient approximation to the full Wasserstein (earth mover's) distance.

1. Generate 4 fixed random projection directions (deterministic LCG PRNG, const-computed at compile time)
2. Project both current and previous amplitude vectors onto each direction
3. Sort the projected values (Shell sort with Ciura gaps, O(n^1.3))
4. Compute 1D Wasserstein-1 distance between sorted projections (just mean absolute difference)
5. Average across all 4 projections
6. Smooth via EMA and compare against thresholds

Subtle motion detection: When the Wasserstein distance is elevated (distribution shape changed) but the variance is stable (total power unchanged), something moved without creating obvious disturbance -- e.g., slow hand motion, breathing, or a door slowly closing.

Public API

pub struct OptimalTransportDetector { /* ... */ }

impl OptimalTransportDetector {
    pub const fn new() -> Self;
    pub fn process_frame(&mut self, amplitudes: &[f32]) -> &[(i32, f32)];
    pub fn distance() -> f32;            // EMA-smoothed Wasserstein distance
    pub fn variance_smoothed() -> f32;   // EMA-smoothed variance
    pub fn frame_count() -> u32;
}

Events

Configuration

Tutorial: Interpreting Wasserstein Distance

The Wasserstein distance measures the "cost" of transforming one distribution into another. Unlike variance-based metrics that only measure spread, it captures changes in shape, location, and mode structure.

Typical values:

• 0.00-0.05: No motion. Static environment.
• 0.05-0.15: Breathing, subtle body sway, environmental drift.
• 0.15-0.30: Walking, arm movement, normal activity.
• 0.30+: Large motion, multiple people moving, or sudden environmental change.

Why "subtle motion" matters: A person sitting still and slowly raising their hand creates almost no change in total signal variance, but the Wasserstein distance increases because the spatial distribution of signal strength shifts. This is critical for:

• Fall detection (pre-fall sway)
• Gesture recognition (micro-movements)
• Intruder detection (someone trying to move stealthily)

Performance Budget

All latencies are estimated for ESP32-S3 running WASM3 interpreter at 240 MHz. Actual performance varies with subcarrier count and frame complexity.

Memory Layout

All modules use fixed-size stack/static allocations. No heap, no alloc, no Vec. This is required for no_std WASM deployment on the ESP32-S3.

Total static memory for all 6 signal modules: approximately 15 KB, well within the ESP32-S3's available WASM linear memory.