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 controller validation is still limited. 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 hallway and a living room are two devices, not one.

CSI on the device, motion state off it

The architecture puts CSI processing on the ESP32 and only publishes the result. That is the design decision that matters for privacy: applications react to a motion state and a movement score without raw sensing data leaving for a cloud service. 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 calls the complete hosted workflow. 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 the wrapper with no arguments 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.9.0, aioesphomeapi==46.3.0, esptool==5.3.1 and cryptography==50.0.1, the last used for firmware and release catalog signatures. Note the comment on paho-mqtt==1.6.1: it is required by ESPHome 2026.9.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

ML work is separated. requirements.txt states that ML environments must update through requirements-ml.txt, so numpy and the training stack do not come from the main file.

Where ESPectre is the wrong tool

The README's own limitations section is 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, and the documentation does not claim otherwise. 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 still being validated across controller ecosystems, and that a controller may support standard Matter occupancy sensors without having been tested with current firmware. 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

The related searches around this project mix it with RuView, Tommysense and DensePose from WiFi, which is a sign of how people arrive at it. The comparison worth drawing is architectural rather than feature-by-feature, because the projects do not sit at the same layer.

DensePose from WiFi is research work aimed at estimating human pose from Wi-Fi signals, typically with heavier computation and a research pipeline behind it. 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-09-21. Recent releases include 3.0.0-rc2 on 2026-09-16, described as signed firmware, CSI capture controls and standalone SDK builds, plus a snapshot-dev development build on 2026-08-22 and a snapshot preview build on 2026-05-21. The 3.0.0 line is at release candidate, which is the fact that should set your expectations about interface stability.

Upgrade cost is driven by the Python pinning. requirements.txt ties the toolchain to esphome==2026.9.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, the signed-firmware note in 3.0.0-rc2 means signature verification is part of the release path; cryptography==50.0.1 is listed as required for firmware and release catalog signatures, so a host without it cannot validate what it downloads.

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 states controller validation is still limited. 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