Skip to content

Latest commit

 

History

History
140 lines (113 loc) · 7.92 KB

ADR-048-adaptive-csi-classifier.md

File metadata and controls

140 lines (113 loc) · 7.92 KB

ADR-048: Adaptive CSI Activity Classifier

Field Value
Status Accepted
Date 2026-03-05
Deciders ruv
Depends on ADR-024 (AETHER Embeddings), ADR-039 (Edge Processing), ADR-045 (AMOLED Display)

Context

WiFi-based activity classification using ESP32 Channel State Information (CSI) relies on hand-tuned thresholds to distinguish between activity states (absent, present_still, present_moving, active). These static thresholds are brittle — they don't account for:

  • Environment-specific signal patterns: Room geometry, furniture, wall materials, and ESP32 placement all affect how CSI signals respond to human activity.
  • Temporal noise characteristics: Real ESP32 CSI data at ~10 FPS has significant frame-to-frame jitter that causes classification to jump between states.
  • Vital signs estimation noise: Heart rate and breathing rate estimates from Goertzel filter banks produce large swings (50+ BPM frame-to-frame) at low confidence levels.

The existing threshold-based approach produces noisy, unstable classifications that degrade the user experience in the Observatory visualization and the main dashboard.

Decision

1. Three-Stage Signal Smoothing Pipeline

All CSI-derived metrics pass through a three-stage pipeline before reaching the UI:

Stage 1: Adaptive Baseline Subtraction

  • EMA with α=0.003 (~30s time constant) tracks the "quiet room" noise floor
  • Only updates during low-motion periods to avoid inflating baseline during activity
  • 50-frame warm-up period for initial baseline learning
  • Subtracts 70% of baseline from raw motion score to remove environmental drift

Stage 2: EMA + Median Filtering

  • Motion score: Blended from 4 signals (temporal diff 40%, variance 20%, motion band power 25%, change points 15%), then EMA-smoothed with α=0.15
  • Vital signs: 21-frame sliding window → trimmed mean (drop top/bottom 25%) → EMA with α=0.02 (~5s time constant)
  • Dead-band: HR won't update unless trimmed mean differs by >2 BPM; BR needs >0.5 BPM
  • Outlier rejection: HR jumps >8 BPM/frame and BR jumps >2 BPM/frame are discarded

Stage 3: Hysteresis Debounce

  • Activity state transitions require 4 consecutive frames (~0.4s) of agreement before committing
  • Prevents rapid flickering between states
  • Independent candidate tracking resets on new direction changes

2. Adaptive Classifier Module (adaptive_classifier.rs)

A Rust-native environment-tuned classifier that learns from labeled JSONL recordings:

Feature Extraction (15 features)

# Feature Source Discriminative Power
0 variance Server Medium — temporal CSI spread
1 motion_band_power Server Medium — high-frequency subcarrier energy
2 breathing_band_power Server Low — respiratory band energy
3 spectral_power Server Low — mean squared amplitude
4 dominant_freq_hz Server Low — peak subcarrier index
5 change_points Server Medium — threshold crossing count
6 mean_rssi Server Low — received signal strength
7 amp_mean Subcarrier Medium — mean amplitude across 56 subcarriers
8 amp_std Subcarrier High — amplitude spread (motion increases spread)
9 amp_skew Subcarrier Medium — asymmetry of amplitude distribution
10 amp_kurt Subcarrier High — peakedness (presence creates peaks)
11 amp_iqr Subcarrier Medium — inter-quartile range
12 amp_entropy Subcarrier High — spectral entropy (motion increases disorder)
13 amp_max Subcarrier Medium — peak amplitude value
14 amp_range Subcarrier Medium — amplitude dynamic range

Training Algorithm

  • Multiclass logistic regression with softmax output
  • Mini-batch SGD (batch size 32, 200 epochs, linear learning rate decay)
  • Z-score normalisation using global mean/stddev computed from all training data
  • Per-class statistics (mean, stddev) stored for Mahalanobis distance fallback
  • Deterministic shuffling (LCG PRNG, seed 42) for reproducible results

Training Data Pipeline

  1. Record labeled CSI sessions via POST /api/v1/recording/start {"id":"train_<label>"}
  2. Filename-based label assignment: *empty*→absent, *still*→present_still, *walking*→present_moving, *active*→active
  3. Train via POST /api/v1/adaptive/train
  4. Model saved to data/adaptive_model.json, auto-loaded on server restart

Inference Pipeline

  1. Extract 15-feature vector from current CSI frame
  2. Z-score normalise using stored global mean/stddev
  3. Compute softmax probabilities across 4 classes
  4. Blend adaptive model confidence (70%) with smoothed threshold confidence (30%)
  5. Override classification only when adaptive model is loaded

3. API Endpoints

Method Endpoint Description
POST /api/v1/adaptive/train Train classifier from train_* recordings
GET /api/v1/adaptive/status Check model status, accuracy, class stats
POST /api/v1/adaptive/unload Revert to threshold-based classification
POST /api/v1/recording/start Start recording CSI frames (JSONL)
POST /api/v1/recording/stop Stop recording
GET /api/v1/recording/list List available recordings

4. Vital Signs Smoothing

Parameter Value Rationale
Median window 21 frames ~2s of history, robust to transients
Aggregation Trimmed mean (middle 50%) More stable than pure median, less noisy than raw mean
EMA alpha 0.02 ~5s time constant — readings change very slowly
HR dead-band ±2 BPM Prevents display creep from micro-fluctuations
BR dead-band ±0.5 BPM Same for breathing rate
HR max jump 8 BPM/frame Outlier rejection threshold
BR max jump 2 BPM/frame Outlier rejection threshold

Consequences

Benefits

  • Stable UI: Vital signs readings hold steady for 5-10+ seconds instead of jumping every frame
  • Environment adaptation: Classifier learns the specific room's signal characteristics
  • Graceful fallback: If no adaptive model is loaded, threshold-based classification with smoothing still works
  • No external dependencies: Pure Rust implementation, no Python/ML frameworks needed
  • Fast training: 3,000+ frames train in <1 second on commodity hardware
  • Portable model: JSON serialisation, loadable on any platform

Limitations

  • Single-link: With one ESP32, the feature space is limited. Multi-AP setups (ADR-029) would dramatically improve separability.
  • No temporal features: Current frame-level classification doesn't use sequence models (LSTM/Transformer). Could be added later.
  • Label quality: Training accuracy depends heavily on recording quality (distinct activities, actual room vacancy for "empty").
  • Linear classifier: Logistic regression may underfit non-linear decision boundaries. Could upgrade to 2-layer MLP if needed.

Future Work

  • Online learning: Continuously update model weights from user corrections
  • Sequence models: Use sliding window of N frames as input for temporal pattern recognition
  • Contrastive pretraining: Leverage ADR-024 AETHER embeddings for self-supervised feature learning
  • Multi-AP fusion: Use ADR-029 multistatic sensing for richer feature space
  • Edge deployment: Export learned thresholds to ESP32 firmware (ADR-039 Tier 2) for on-device classification

Files

File Purpose
crates/wifi-densepose-sensing-server/src/adaptive_classifier.rs Adaptive classifier module (feature extraction, training, inference)
crates/wifi-densepose-sensing-server/src/main.rs Smoothing pipeline, API endpoints, integration
ui/observatory/js/hud-controller.js UI-side lerp smoothing (4% per frame)
data/adaptive_model.json Trained model (auto-created by training endpoint)
data/recordings/train_*.jsonl Labeled training recordings