ESPectre
Run ESPectre on MicroPython
Capture Wi-Fi CSI and detect motion in MicroPython, using the CSI support that ESPectre added to MicroPython itself.
Sections
ESPectre brought ESP32 CSI to mainline MicroPython
ESPectre added Wi-Fi CSI access to MicroPython in micropython/micropython#18460. New ESP32 network.WLAN methods let Python code capture CSI, read it from a buffer, and count dropped frames.
The change was merged for MicroPython 1.29.0, so any MicroPython project can now use CSI on the ESP32. Micro-ESPectre builds on an official MicroPython version instead of the old CSI fork.
What runs on the ESP32
The device loop runs in MicroPython on the board. CSI capture uses MicroPython. Filtering, Lightweight detection, traffic generation, and HTTP delivery use native components from the C++ SDK. The device reports motion and a movement score; it does not send raw CSI.
Detector changes are tried in host-side Python first, then ported into the shared C++ code that the device runs. Messages use the same protocol as the other firmware types.
Requirements
| Requirement | Current support |
|---|---|
| Board | ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C5, or ESP32-C6. |
| Radio | Steady Wi-Fi traffic on 2.4 GHz. ESP32-C5 also captures a 5 GHz link as vht20. Detection quality on 5 GHz is not measured yet. |
| Firmware | The ESPectre MicroPython image, built from an official MicroPython version |
| Host setup | The ESPectre repository and its ./espectre command |
| Monitoring | A browser or client on the same local network |
CLI workflow
The ./espectre command builds and flashes MicroPython, then copies Micro-ESPectre to the board and checks it.
Prepare the repository
Create a Python virtual environment and install the requirements.
Build and flash MicroPython
Choose your chip. The command builds the MicroPython image and installs it over USB.
Copy and run Micro-ESPectre
Create your local configuration from the example, then copy Micro-ESPectre to the device and start it.
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp src/python/micro_espectre/config_local.py.example \
src/python/micro_espectre/config_local.py
./espectre micro flash --chip c3 --erase
./espectre micro deploy
./espectre micro verify
./espectre micro runconfig_local.py. Never commit that local file.Lightweight sensing
Micro-ESPectre runs only the Lightweight detector, which calibrates its threshold at startup while the room is quiet. The High Accuracy code stays in the repository for research and testing, but is not copied to the device.
Over Direct HTTP, Micro-ESPectre provides health, device, capabilities, sensing, wifi, and diagnostics. Its only action is recalibration, and its events stream sends motion updates only. It also prints its status on the serial port every second. It publishes its DNS-SD service, so ./espectre devices --frontend micro can list it. Browser Auto-discovery still needs a Native, ESPHome, or commissioned Matter device on the LAN: Micro does not answer the bootstrap name or GET /devices. It has no MQTT, raw CSI stream, or Home Assistant support.
Current role and limits
Micro-ESPectre is where we experiment in Python. It is not a stable library yet: you install the whole application, and its public interface may still change.
- Only the Lightweight detector is available.
- Settings are read-only while running; to change them, edit the files and deploy again.
- No Bluetooth setup and no over-the-air updates.
- Changes reach the production firmware only after they are ported to C++ and tested to give the same results.
For configuration, the Direct API, and development checks, see the Micro-ESPectre reference.