Collect CSI data for machine learning

Record labelled Wi-Fi measurements from your room, check their quality, and prepare them for research or a contribution to the High Accuracy model.

What you need

• An ESPectre device running Native, ESPHome, or Matter firmware, with Direct enabled. Follow the setup guide if you need to install one.
• A computer that can reach the device on the local network, with Python 3.14 and a copy of the ESPectre repository on GitHub.
• A room where you can record quiet periods, a person sitting still, and movement without mixing those activities in one recording.

The collector sends Wi-Fi traffic to the device and receives its raw CSI over HTTP. It saves a compressed NumPy file (.npz) for each device and recording. Micro-ESPectre does not expose the raw CSI stream needed for this workflow.

Prepare the collector

From the repository root, create the Python environment and install the dependencies:

python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

In Windows PowerShell, activate with .venv\Scripts\Activate.ps1 and use .\espectre.cmd instead of ./espectre.

Find the device’s address in Device settings, then try a live preview. Replace the example IP with your device’s address:

./espectre collect --target 192.168.1.50

Without a label, this shows the stream without saving a dataset. Press Ctrl+C to stop. You can also inspect the signal in the browser with the CSI visualizer.

Choose the right label

static_presence teaches the motion detector to remain idle when someone is still. It does not train a separate stationary-presence state.

Record a session

Run one command at a time, arranging the room for that label before each capture. Keep still until the collector reports that recording has started; for motion, then begin moving.

./espectre collect --label empty --duration 60 --target 192.168.1.50
./espectre collect --label static_presence --duration 60 --target 192.168.1.50
./espectre collect --label motion --duration 60 --target 192.168.1.50

The collector waits for the detector to be ready and below threshold before saving. Lightweight needs to finish calibration; High Accuracy needs a full feature window. Leave the readiness check enabled for normal collection.

Aim for 30–60 seconds per recording and at least 10 recordings per label if you can. Keep each static_presence and motion pair in comparable conditions: the same room, device placement, and radio setup. Vary the person’s position and distance across pairs.

Collection switches the device to external traffic mode and leaves it there afterwards. When finished, use Device settings to restore your previous traffic mode if the sensor normally generates its own traffic.

Describe and check the recordings

The collector creates entries in data/dataset_info.json with the technical metadata. Add an environment name for the room and start with dataset_role set to exclude while you review the data. Use the same room name across its recordings, and describe anything unusual in description.

./espectre collect --info
python tools/validate_dataset_quality.py

The first command lists the recordings. The validator checks capture quality, creates the pair fields, and writes data/auto_generated/DATASET_QUALITY_CHECK.md. Fix every FAIL before submitting data or training. Do not add pair fields manually; the validator owns them.

Dataset roles decide which recordings are used for training, model selection, or the final test. Validation does not assign those roles. See the dataset reference on GitHub for the catalog schema and quality criteria.

Contribute a dataset

Recordings from different chips, routers, and room layouts help test how well the model generalizes. Include the labelled files, their catalog entries, a short description of the setup, and a passing quality report in your pull request against develop.

CSI contains no images or audio, but its metadata and activity patterns can reveal private information. Tell the people involved before recording, and inspect both the NPZ metadata and catalog before sharing. Remove unnecessary identifying details; never submit Wi-Fi passwords, SSIDs, BSSIDs, local IP addresses, serial logs, or unrelated personal data.

Read the contribution terms on GitHub before submitting. To work on the model itself, continue with the ML training reference on GitHub.