MICROPYTHON · 4 MIN READ

Run ESPectre on MicroPython

Capture ESP32 Wi-Fi CSI and run motion sensing directly on the device using the upstream MicroPython support contributed by ESPectre.

A Python snake mascot perched on an Espressif board connected to a laptop displaying CSI traces — MicroPython captures CSI on the ESP32; Micro-ESPectre turns the stream into on-device motion signals and local telemetry.

ESPectre brought ESP32 CSI to mainline MicroPython

ESPectre contributed direct Wi-Fi Channel State Information access to MicroPython through micropython/micropython#18460. The merged ESP32 network.WLAN methods expose CSI capture, buffered reads, availability, and dropped-frame diagnostics from Python.

Micro-ESPectre now uses pinned, hash-verified official MicroPython firmware rather than the historical project fork. The contribution was merged into mainline for the MicroPython 1.29.0 release cycle, so other MicroPython projects can use the same ESP32 CSI interface.

The durable claim is the contribution itself: ESPectre added direct ESP32 CSI access to mainline MicroPython, and then built an on-device sensing runtime on top of it.

What runs on the ESP32

Micro-ESPectre is not a desktop Python backend. CSI capture, temporal admission, feature extraction, detection, motion-state filtering, traffic generation, and telemetry all run on the microcontroller. Normal operation publishes derived motion state and movement score; raw CSI is reserved for explicit research and collection workflows.

Wi-Fi trafficrouter

CSI captureMicroPython

Featureson-device Python

Detectionon-device Python

MQTT eventlocal network

The Python and C++ implementations follow the same detector design. Shared CSI format, timing, feature, threshold, and protocol contracts stay aligned so Python experiments can be validated before stable behavior is promoted to the production C++ layers.

Requirements

Requirement	Current support
Board	ESP32, ESP32-C3, ESP32-C5, ESP32-C6, or ESP32-S3
Radio	2.4 GHz Wi-Fi and incoming traffic for CSI capture
Firmware	Official MicroPython firmware with ESP32 CSI support
Host setup	The ESPectre repository environment and `./espectre` wrapper
Telemetry	An MQTT broker when remote monitoring or Home Assistant Discovery is needed

CLI workflow

The repository wrapper owns the complete MicroPython device flow, from installing the verified upstream firmware to deploying and checking Micro-ESPectre.

Prepare the repository environment
Create the project virtual environment and install the base requirements.
Flash official MicroPython
The wrapper selects the supported board firmware, verifies its hash, and installs it over USB.
Deploy and run Micro-ESPectre
Create the local configuration from the provided example, then copy the runtime 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 --erase
./espectre micro deploy
./espectre micro verify
./espectre micro run

Keep Wi-Fi and MQTT credentials in config_local.py. Never commit that local file.

The same two detection profiles

Profile	Choose it when	Startup
Lightweight	You want the leaner detector and fast Python-side iteration.	Adapts its threshold from clean, ready quiet-room coverage.
High Accuracy	You can spend more memory and inference work for better detection quality.	Uses its trained threshold, then waits for CSI and feature-window readiness.

Both publish through the ESPectre Protocol message model used by the Native frontend. Micro-ESPectre can also enable an optional Home Assistant MQTT Discovery adapter for motion, movement score, controls, and on-demand diagnostics.

Current role and limits

Micro-ESPectre is ESPectre's maintained Python and MicroPython experimentation path. It is not yet presented as a stable embeddable SDK: the current distribution deploys the complete reference runtime, and its supported public library boundary has not been frozen.

Detector selection is made at deployment time rather than switched at runtime.
Runtime control changes are session-only unless device code explicitly persists them.
Bluetooth provisioning and OTA are not implemented on the MicroPython path.
Production changes still require aligned C++ behavior and parity validation.

For configuration, MQTT topics, Home Assistant entities, implementation detail, and development checks, continue with the maintained Micro-ESPectre reference.