francescopace/espectre 2.2.0

v2.2.0 - Gain Lock, Low-Pass Filter & ML Data Collection

on GitHub

This release focuses on signal stability and noise reduction. A new two-phase calibration process locks the WiFi automatic gain control before NBVI calibration, ensuring clean and consistent CSI data across devices. The new low-pass Butterworth filter effectively removes high-frequency RF noise, dramatically reducing false positives in challenging environments. Additionally, new CLI tools for labeled data collection lay the foundation for machine learning capabilities in the upcoming 3.x series.

Gain Lock (AGC/FFT Stabilization)

Automatic gain control locking for stable CSI measurements, based on Espressif esp-csi recommendations.

• Two-phase calibration: Gain Lock (3s, 300 pkt) → NBVI (7s, 700 pkt)
• Gain lock happens BEFORE NBVI calibration to ensure clean data
• Eliminates amplitude variations caused by automatic gain control
• Supported on ESP32-S3, C3, C5, C6 (not available on ESP32, S2)
• New files: gain_controller.h, gain_controller.cpp

Baseline Variance Normalization

Automatic attenuation for consistent thresholds across devices and environments.

• Always enabled - no configuration needed
• During calibration, calculates baseline variance using selected subcarriers
• If baseline > 0.25: attenuate with scale = 0.25 / baseline_variance
• If baseline ≤ 0.25: no scaling needed (scale = 1.0)
• Prevents over-amplification of weak signals while taming strong ones
• Removed normalization_enabled and normalization_target parameters

Low-Pass Filter

New 1st order Butterworth IIR filter to reduce high-frequency RF noise.

• Cutoff frequency: 11 Hz (human movement: 0.5-10 Hz, RF noise: >15 Hz)
• Reduces false positives in noisy environments (51% → 2%)
• Disabled by default: enable with lowpass_enabled: true
• Processing pipeline: Normalization → Hampel → Low-Pass → Buffer

NBVI Improvements

Optimized parameters and restricted search range for better subcarrier selection:

Dynamic null subcarrier detection replaces hardcoded lists - adapts to local RF conditions.

Performance

Lazy Variance Evaluation: Moving variance calculated only at publish time.

• ~99% CPU savings for variance calculation
• New API: csi_processor_update_state() (C++), seg.update_state() (Python)

Automatic sdkconfig

The ESPHome component now auto-configures all required sdkconfig options:

• CONFIG_ESP_WIFI_CSI_ENABLED, CONFIG_PM_ENABLE, AMPDU settings, buffer sizes, tick rate
• YAML files only need platform-specific options (WiFi 6, CPU frequency, PSRAM)

ML Data Collection

New infrastructure for building labeled CSI datasets (groundwork for 3.x):

• me collect CLI subcommand for recording labeled samples
• .npz format for ML-ready datasets
• csi_utils.py module with CSIReceiver, CSICollector, MVSDetector

Configuration Changes

Removed options (now automatic):

• normalization_enabled, normalization_target, manual sdkconfig options

Default values: All filters disabled, normalization always active.

Enhanced logging: Movement logs now include WiFi channel and RSSI:

[I][espectre]: [######--|----] 43% | mvmt:0.43 thr:1.00 | IDLE | 101 pkt/s | ch:3 rssi:-47

Testing & Documentation

• 324 pytest tests with CI integration (test-python job)
• Python coverage uploaded to Codecov
• New micro-espectre/ALGORITHMS.md with scientific documentation of MVS, NBVI, Hampel filter