$ show francescopace/espectre
ESPectre is a production-grade Wi-Fi motion sensing system that runs on ESP32 microcontrollers. It captures Channel State Information (CSI) from Wi-Fi packets and runs on-device detection algorithms (Lightweight turbulence-based and High Accuracy neural network) to detect human motion without cameras or microphones. The system is designed for local-first operation with no cloud dependency, integrating with Home Assistant via ESPHome, MQTT, or Matter. The architecture is layered: a core sensing layer handles CSI capture, filtering, and feature extraction; a runtime layer manages lifecycle, configuration, and diagnostics; and multiple frontend adapters (native MQTT/HTTP, ESPHome, Matter, MicroPython) expose motion events to home automation systems. A Python CLI provides device discovery, flashing, monitoring, and dataset analysis tools. A web interface at espectre.dev offers browser-based device management. The repository also includes a significant data/research component: a published dataset of CSI recordings, ML training infrastructure, dataset quality validation pipelines, and performance benchmarking tools. These support the development and validation of the detection algorithms and ensure cross-language parity between C++ firmware and Python reference implementations. The codebase demonstrates strong engineering practices: interface-based design for testability, extensive unit and integration tests with coverage gates, cross-language parity enforcement, and a comprehensive CI/CD pipeline. Multiple frontends share a common core SDK, reducing duplication while allowing platform-specific optimizations.
The LLM identified 5 files worth highlighting for reuse:
A robust outlier rejection filter based on Median Absolute Deviation (Hampel filter). Implemented in both C++ (for firmware) and Python (for host tools), it provides stateful and stateless variants. The filter is self-contained, well-tested, and can be extracted for any time-series filtering task.
Implements a fixed-grid temporal admission strategy for CSI packets, ensuring consistent sampling rates despite variable packet arrival. Features slot competition, gap detection, and occupancy tracking. The algorithm is isolated and could be reused for any sensor sampling problem requiring rate control.
A hand-rolled, single-pass JSON parser designed for resource-constrained embedded devices. It avoids dynamic allocation and provides safe string extraction, key lookup, and URL-encoded pair parsing. Demonstrates careful memory management and can be reused in any embedded project needing minimal JSON parsing.
A gain-invariant feature extractor that analyzes the trajectory of CSI channel shapes over physical time bins. Uses DCT modes, Kendall distance, and motion participation ratio to produce scale-invariant features for ML-based detection. The algorithm is self-contained and applicable to any multi-subcarrier CSI analysis.
A comprehensive validation framework for CSI datasets, covering capture integrity, signal quality, temporal occupancy, ML readiness, and idle evidence scoring. Produces structured reports with per-capture scores and severity thresholds. The modular design (metrics, pairing, readiness, rendering) allows adaptation to other sensor dataset validation tasks.