francescopace/espectre 2.3.0

v2.3.0 - End of Year Edition 🎉

on GitHub

As a thank you to the community, I'm closing the year with something fun: a browser-based reaction game where your physical movement controls the gameplay through WiFi sensing. No controller needed (but mouse is supported as alternative)!

Beyond the fun, it's actually useful for threshold tuning, calibration verification, and coverage testing. Uses Web Serial API (Chrome/Edge) with real-time CSI streaming at ~100 Hz.

Play now espectre.dev/game and share your high score in the Discussions!

New Features

Sensor Entity Customization

Full control over exposed sensor entities with standard ESPHome options: internal, icon, filters, disabled_by_default.

espectre:
  movement_sensor:
    name: "Movement"
    internal: true
    filters:
      - multiply: 100
  motion_sensor:
    icon: "mdi:motion-sensor"

See #51.

External Traffic Mode

Support for multi-device deployments with reduced network overhead.

• traffic_generator_rate: 0: Disable internal traffic generator and rely on external WiFi traffic
• publish_interval: Control sensor update rate independently from traffic source
• UDP Listener: Opens port 5555 to receive external UDP packets for CSI generation
• 95% less network overhead: One broadcast source feeds all ESPectre devices

External traffic source: espectre_traffic_generator.py - standalone script with daemon mode and Home Assistant integration.

See #50.

Traffic Generator Ping Mode

New traffic_generator_mode: ping option using ICMP echo requests instead of DNS queries. Use when DNS mode has low packet rates (~18 pps instead of ~100 pps) due to routers not responding to root domain queries.

See #48.

Gain Lock Mode

New gain_lock option to control AGC/FFT gain locking behavior:

• auto (default): Enable gain lock but skip if signal too strong (AGC < 30)
• enabled: Always force gain lock (may freeze if too close to AP)
• disabled: Never lock gain (less stable CSI but works at any distance)

Solves the issue where devices too close to the AP (RSSI > -40 dB) would freeze during calibration. See TUNING.md for AGC threshold details.

Improvements

WiFi Channel Change Detection

Automatic detection and buffer reset when AP switches channel (auto-channel, roaming), preventing false positives from CSI data spikes.

Fixes #46.

Multi-Window NBVI Calibration

Optimized subcarrier selection with multi-window validation, gain lock phase exclusion (first 300 packets), and updated noise gate percentile (10% → 25%).

Calibration Fallback with Normalization

When NBVI calibration fails, normalization is still calculated and default subcarriers [11-22] are used, preventing 2000%+ motion values from missing normalization.

Platform Support

ESP32-C3 Super Mini Tested

Added example configuration espectre-c3.yaml. Full feature support including gain lock and NBVI calibration.

ESP32 (Original/WROOM-32) Tested

Tested on ESP32-WROOM-32D Mini (CH340). Fixed NBVI calibration not starting on platforms without gain lock.

Known limitations (ESP32 original only):

• AGC/FFT gain lock not available
• External traffic generator must start after ESP32 connects to WiFi
• Broadcast mode not supported; use unicast instead

See espressif/esp-csi#247.