ESPectre: Wi-Fi CSI motion sensing on an ESP32, with four firmware paths

What ESPectre actually measures, and who ends up using it

A person walking through a room changes how Wi-Fi signals propagate through it. ESPectre reads those changes from channel state information on a supported ESP32 and reports a motion state plus a movement score. The README is explicit that this is a change detector, not an identity system: it does not identify people, count them, or prove a room is empty, and it is not a replacement for a safety-certified security, medical or emergency system.

The audience follows from that boundary. Home Assistant users get native entities through the ESPHome frontend or MQTT with Home Assistant MQTT Discovery. Makers building standalone sensors use the Native frontend. Matter controllers with occupancy-sensor support are a third target, with the caveat that Amazon Alexa and Samsung SmartThings are not tested yet. MicroPython users get Micro-ESPectre, a lighter implementation with local, read-only Direct HTTP monitoring. The repository also carries an open dataset, open model weights and the ML workflow, so a fourth audience exists: people who want to train or inspect the detector rather than just flash it.

Coverage is the constraint that shapes deployments. The README states one board covers one sensing area, and room-level coverage normally requires one board per room. A multi-room deployment may therefore need multiple devices, but radio layout and tuning affect actual coverage; test the intended spaces before deciding the device count.

CSI on the device, motion state off it

The architecture puts motion detection on the ESP32 and normally reports a motion state and score. Motion detection runs locally and does not require a cloud service. The project also supports optional raw CSI collection for research and debugging, so do not assume raw measurements can never leave the device. Motion data itself can reveal routines or presence; review enabled collection, integrations and access controls. The repository documents the acquisition side in docs/CSI.md and the algorithms in docs/ALGORITHMS.md, with docs/ARCHITECTURE.md covering the runtime.

Output paths differ by frontend. The Native frontend targets standalone sensors and MQTT integrations. The ESPHome frontend exposes entities to Home Assistant and supports ESPHome provisioning and Device Builder updates. The Matter frontend presents a standard Matter occupancy sensor. Micro-ESPectre offers a local, read-only Direct HTTP interface. There is also a Direct HTTP API on the main firmware and a C++ SDK for embedding sensing in custom ESP32 firmware.

Device discovery is a separate concern, handled with zeroconf on the host side per requirements.txt, and described in docs/DISCOVERY.md. The host tooling is a Python CLI, which is why the repository's primary language is listed as Python even though the sensing core is C++.

Installing ESPectre: browser flashing first, local build second

The README recommends the browser path for a first device because it needs no local build environment. Open the flash tool in desktop Chrome 151 or later, which the README names as the browser for the quickest path. Edge supports browser flashing, but the README does not guarantee compatibility with Device settings and Monitor.

# Browser workflow, no local toolchain:
# 1. Open https://espectre.dev/tools/flash/
# 2. Connect a supported ESP32 over USB
# 3. Choose a firmware and release channel
# 4. Complete on-screen Wi-Fi provisioning

After provisioning, the README points at two more hosted tools. Device settings lets you pin a preferred access point or set up MQTT. Monitor is where you watch motion, tune detection and inspect the device. Matter commissioning is an alternative to Wi-Fi provisioning, done with a supported controller.

For local builds and flashing from the repository, the README directs you to docs/SETUP.md and exposes the workflows through a wrapper. Running it with --help prints the available commands:

./espectre --help

On Windows the repository ships espectre.cmd alongside the espectre wrapper. Python dependencies are pinned in requirements.txt, including esphome==2026.10.0, aioesphomeapi==46.12.0, esptool==5.4.0 and cryptography==50.0.2 (48.0.1 on Intel macOS), the last used for firmware and release catalog signatures. Note the comment on paho-mqtt==1.6.1: it is required by ESPHome 2026.10.0 and the file says to avoid 2.x. If you already have paho-mqtt 2.x in the same environment, that pin is the first thing to check.

python -m pip install -r requirements.txt

requirements.txt pins numpy==2.5.4 with a comment that ML environments must update through requirements-ml.txt.

Where ESPectre is the wrong tool

The README's own caveats are the honest starting point, and it rules out several use cases outright. ESPectre detects changes in the radio environment. It does not identify people, it does not count them, and it cannot prove a room is empty. If your automation needs a headcount, or an audit trail of who entered, this is not the project.

Presence and absence are different problems. A motion detector that fires on radio disturbance will also fire on other disturbance. Anything that must be safe when it fails, such as a medical alert or an emergency system, is outside scope by the README's own statement.

Hardware is a hard gate. Supported parts are ESP32-C6, ESP32-C5, ESP32-C3, ESP32-S3, ESP32-S2 and classic ESP32, on a normal Wi-Fi 4 (802.11n) network at 2.4 GHz. A board outside that list is not a tuning problem. Density is the other gate: one board covers one sensing area, so a whole-home deployment multiplies cost and provisioning work by the number of rooms.

The Matter frontend carries its own warning. The README says it is tested with Google Home, Apple Home and Home Assistant, that Amazon Alexa and Samsung SmartThings are not tested yet, and that Google Home needs a one-time Developer Console setup. The Matter README links to a compatibility matrix. Treat Matter as the least settled of the four paths and check that matrix before buying hardware for it.

ESPectre against the Wi-Fi sensing projects people compare it with

ESPectre is best compared with other Wi-Fi sensing projects at the architectural level rather than feature by feature.

ESPectre targets a motion state and a movement score on an ESP32, with the processing on the device and the result published over MQTT, ESPHome, Matter or HTTP. If your goal is pose estimation, ESPectre's README does not claim to do it, and the detector output it describes is a state and a score, not a skeleton.

Against other ESP32 Wi-Fi sensing projects, the difference is the surface area rather than the sensing idea. ESPectre ships four firmware paths, a C++ SDK, a MicroPython port, browser flashing and monitoring tools, a host CLI, an open dataset, open model weights and the training workflow, plus a documented architecture and algorithm set. That breadth is the reason to pick it, and also the reason the repository is large. If you want a single sketch to read and modify, the extra paths are overhead you will not use.

Licence, maintenance and what an upgrade costs you

ESPectre is GPL-3.0. The repository carries LICENSE, LICENSING.md and THIRD_PARTY_NOTICES.md, and the description mentions commercial licensing alongside GPLv3. If you plan to embed the C++ SDK in a product, or to redistribute modified firmware, read LICENSING.md and THIRD_PARTY_NOTICES.md before you design around it. That is a licensing question for your own counsel, not something this article can settle.

The repository is not archived, and the last push was on 2026-11-02. Recent releases include 3.1.0 (Matter controller compatibility and external traffic sources) on 2026-11-01, plus a snapshot-dev development build on 2026-08-22 and a snapshot preview build on 2026-05-21.

Upgrade cost is driven by the Python pinning. requirements.txt ties the toolchain to esphome==2026.10.0 with matching aioesphomeapi, esptool and cryptography versions, and warns against paho-mqtt 2.x. Moving one of those forward alone is likely to break the others, so treat the file as a set. On the firmware side, requirements.txt lists cryptography (50.0.2, or 48.0.1 on Intel macOS) for firmware and release catalog signatures.

Verifying an ESPectre deployment before you rely on it

Start with the hardware list, not with the automation. Confirm your board is one of ESP32-C6, ESP32-C5, ESP32-C3, ESP32-S3, ESP32-S2 or classic ESP32, and that the network you will sense on is Wi-Fi 4 at 2.4 GHz. Then flash one board through the browser tool and watch it in Monitor before writing any automation. Tuning detection on a single room teaches you what the movement score looks like when nothing is happening, which is the baseline you need for every later room.

For Home Assistant, decide between the ESPHome frontend, which the README recommends for native entities and provisioning, and the Native frontend with MQTT Discovery. Both are documented, and the choice affects how you update devices later. If you want Matter, read the compatibility matrix in the Matter README before assuming your controller is covered.

The repository's documentation index is the map for everything else. docs/SETUP.md and docs/CLI.md cover install and operation, docs/TROUBLESHOOTING.md covers failures, docs/API.md and docs/DISCOVERY.md cover integration, and docs/ML_DATA_COLLECTION.md with docs/ML_TRAINING.md cover the training path. docs/performance/README.md holds the performance report, which is where to look before assuming a given board and room will behave as you expect.

Editorial conclusion

Adopt ESPectre if you already run a 2.4 GHz Wi-Fi 4 network, want motion state inside Home Assistant or MQTT without a camera, and accept one board per sensing area. Do not adopt it as a security, medical or occupancy-counting system, and do not expect the Matter frontend to work with every controller: the README says Amazon Alexa and Samsung SmartThings are not tested yet. Before committing, read docs/SETUP.md and the frontend README for the path you intend to use, and confirm that your exact board appears in the supported-hardware list, since the project names ESP32-C6, C5, C3, S3, S2 and classic ESP32 and nothing else.

Frequently asked questions

Official sources

1. francescopace/espectre on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases