espectre snapshot-dev
ESPectre - Motion detection system based on Wi-Fi spectre analysis (CSI), with Home Assistant integration.
ESPectre 
Turn an ESP32 into a private, local Wi-Fi motion sensor.
When someone moves through a room, they change the way Wi-Fi signals travel through it. ESPectre reads those changes and reports motion in real time. No camera, no microphone, no wearable, and no dedicated radar hardware: just a supported ESP32 and the Wi-Fi network already in the room.
ESPectre is an open-source platform that brings together ready-to-flash firmware, an embeddable C++ SDK, a MicroPython implementation, browser tools, a host CLI, an open dataset, open model weights, and the research workflow used to build and validate the detectors.
Flash from your browser · See the live tools · Read the documentation · Explore the SDK
Applications and integrations
ESPectre can turn on a display or lights when it detects motion, adjust heating and cooling in response to room activity, trigger an alarm or notification when movement occurs in an area that should be empty, and drive other room automations. It connects to Home Assistant through ESPHome or MQTT, exposes a standard Matter occupancy sensor and a local Direct HTTP API, and can be embedded in custom ESP32 firmware through the C++ SDK.
ESPectre processes CSI on the device and reports a motion state and movement score. Applications can react without sending raw sensing data to a cloud service. One board covers one sensing area; room-level coverage normally requires one board per room.
ESPectre detects changes in the radio environment. It does not identify people, count them, prove that a room is empty, or replace a safety-certified security, medical, or emergency system.
Supported hardware
- ESP32-C6, ESP32-C5, ESP32-C3, ESP32-S3, ESP32-S2, and classic ESP32
- a normal Wi-Fi 4 (802.11n) network on 2.4 GHz
Choose a firmware path
| Path | Best for | Start here |
|---|---|---|
| Native | Standalone sensors, MQTT integrations, including Home Assistant MQTT Discovery, and custom applications | Native frontend |
| ESPHome | Home Assistant users who want native entities, ESPHome provisioning, and Device Builder updates | ESPHome frontend |
| Matter | Matter controllers with occupancy-sensor support; controller validation is still limited | Matter frontend |
| Micro-ESPectre | Lightweight sensing in MicroPython with local, read-only Direct HTTP monitoring | Micro-ESPectre README |
Native, ESPHome, and Matter can choose between a lightweight detector, which learns a room-specific threshold at startup and leaves more resources to the rest of the application, and a high_accuracy detector, which runs the trained model included in the repository. Their behavior and measured trade-offs are documented in SETUP.md, ALGORITHMS.md, and the performance report.
Quick start
The quickest path uses the browser and requires no local build environment. Use desktop Chrome 151 or later for the complete hosted workflow. Edge supports browser flashing, but compatibility with Device settings and Monitor is not guaranteed:
- Open Flash in desktop Chrome or Edge.
- Connect a supported ESP32 over USB, then choose a firmware and release channel.
- Complete on-screen Wi-Fi provisioning, or commission Matter with a supported controller.
- Optionally, open Device settings to pin a preferred access point or set up MQTT.
- Open Monitor to watch motion, tune detection, and inspect the device.
Matter status: The Matter frontend is still being validated across controller ecosystems. A controller may support standard Matter occupancy sensors without having been tested with current firmware. See Matter controller compatibility for the current matrix.
Local setup
For local builds, flashing from this repository, and the rest of the operator path, start with SETUP.md. The repository wrapper exposes the available workflows through:
./espectre --help
Documentation
| Topic | What it covers | Guides |
|---|---|---|
| Install and operate | Device setup, CLI workflows, and detector tuning | SETUP.md, CLI.md, TUNING.md |
| Understand and integrate | Runtime architecture, API, discovery, algorithms, and the C++ SDK | ARCHITECTURE.md, API.md, DISCOVERY.md, ALGORITHMS.md, SDK.md |
| Collect and train | CSI collection, model training, feature history, performance, and literature | ML_DATA_COLLECTION.md, ML_TRAINING.md, FEATURES.md, performance report, LITERATURE.md |
| Research and direction | Roadmap, architecture decisions, and release history | ROADMAP.md, ADR index, CHANGELOG.md |
| Frontend reference | Firmware-path READMEs for ESPHome, Native, Matter, and Micro-ESPectre | ESPHome, Native, Matter, Micro |
| Contributing | How to contribute and where to discuss the project | CONTRIBUTING.md, GitHub Discussions |
Datasets, models, and validation
ESPectre publishes the research assets and validation evidence behind its detectors:
| Asset | What it gives you | Start here |
|---|---|---|
| CSI dataset | Real recordings for empty rooms, static presence, and motion, with catalog and provenance in dataset_info.json | data/ |
| Model weights | Trained weights in C++ and Python, plus the training, export, and validation workflow | ML_TRAINING.md |
| Feature ledger | Features that were tested, promoted, or rejected, including unsuccessful experiments | FEATURES.md |
| Algorithms and reports | Detector behavior, the generated performance report, and the dataset quality report | ALGORITHMS.md |
| Literature and direction | External research, architecture decision records, and the public roadmap | LITERATURE.md |
Security, privacy, and transparency
A sensor that can reveal presence should not be a black box. Wi-Fi sensing avoids images and audio, but motion and occupancy data can still reveal routines, sleep, or absence from home. ESPectre treats that risk as part of the engineering work:
- motion detection is local, and cloud connectivity is not required;
- raw CSI collection is optional and intended for defined research and debugging needs;
- the security and responsible-use guide documents deployment boundaries, consent, data minimization, abuse reporting, and private vulnerability reporting;
- firmware releases include build-specific SBOMs, notices, and license archives so their contents can be inspected;
- the public website and every browser tool are part of this repository under docs/web, including their source, privacy rules, analytics contract, and pinned browser dependencies;
- protocols, algorithms, performance evidence, limitations, roadmap decisions, and known validation boundaries are documented in public.
Use ESPectre only in spaces and networks where you have the right to deploy it. Inform affected people, obtain consent where required, protect access to the device and its data, and follow applicable privacy laws.
Acknowledgments
- Thanks to Espressif for making CSI accessible in ESP-IDF and for recognizing ESPectre as a community project in esp-csi.
- Thanks to the MicroPython maintainers for reviewing, testing, and merging ESPectre's CSI contribution, which added direct CSI methods to mainline
network.WLAN.
License
ESPectre first-party code is available under GPLv3, and eligible parts are also available under a separate commercial agreement:
- Choose GPLv3 when your firmware or application can comply with GPLv3, including making the corresponding source available. See LICENSE.
- If you want to embed ESPectre in proprietary or closed-source firmware without GPLv3 source-disclosure obligations, see LICENSING.md for commercial licensing. The commercial license covers eligible material and does not replace third-party terms; the ESPHome C++ frontend remains GPLv3-only.
Third-party terms and build-specific compliance artifacts are described in THIRD_PARTY_NOTICES.md.