ESP32/doc/TELEMETRY_CAPTURE.md

Telemetry capture

How to enable and capture MCS telemetry (frame rates, MCS indices, RSSI, PHY rates per device) from the ESP32.

Prerequisites

• SD card inserted and mounted (see SD_CARD_WIRING.md)
• Python 3 on the laptop (for host scripts)

1. Enable telemetry on the device

Connect to the device over serial and run:

monitor start [-c <channel>]

This puts the device in WiFi monitor mode and automatically writes MCS telemetry to fiwi-telemetry on the SD card every 10 seconds. No extra configuration needed.

Note: Monitor mode disconnects WiFi. The device will not be on the network while capturing. Use serial (Option A) to capture while in monitor mode. Use WiFi (Option B) when the device is back on the network—e.g. after reboot, or after running monitor stop if you have serial access.

Check telemetry status:

sdcard status

Shows fiwi-telemetry: yes, <size> when telemetry exists.

2. Capture telemetry on a laptop

Option A: Serial (device connected by USB)

Use when the device is in monitor mode (no WiFi) or for any direct USB connection.

On the laptop (device must be reachable over serial; you may need to exit the REPL or connect in a second terminal):

pip install pyserial
python3 tools/sdcard_recv.py -p /dev/ttyUSB0 -f fiwi-telemetry -o fiwi-telemetry.json

The script sends sdcard send fiwi-telemetry to the device and captures the hex-encoded response. No need to type the command on the device.

• -p / --port: serial port (e.g. /dev/ttyUSB0 on Linux, COM3 on Windows)
• -f / --remote: file path on the SD card
• -o / --output: local path to save (default: basename of remote file)

Serial transfer is limited to 512 KB per file.

---

Option B: WiFi + beacon discovery (no device interaction)

Use when the device is on the network (STA mode) and connected to the same LAN as the laptop. No serial or device interaction required—the device advertises itself via UDP broadcast on port 5555. Telemetry must already be on the SD card (from a previous monitor session, e.g. device ran monitor mode in the field, or rebooted back to STA).

On the laptop:

# Listen only (see devices, no download)
python3 tools/beacon_listen.py

# Listen and download fiwi-telemetry from each device
python3 tools/beacon_listen.py --download --output-dir ./telemetry

# Re-download every 60 seconds
python3 tools/beacon_listen.py --download --output-dir ./telemetry --refresh 60

Files are saved as fiwi-telemetry_<mac> in the output directory. Uses standard library only (no pip install).

---

Option C: WiFi + direct HTTP (you know the IP)

If the device is on the network and you know its IP:

curl -o fiwi-telemetry.json "http://<device-ip>:8080/sdcard/fiwi-telemetry"

Or in a browser: http://<device-ip>:8080/sdcard/fiwi-telemetry

Telemetry format

fiwi-telemetry is JSON:

{"device_id":"esp32","timestamp":12345,"total_frames":1000,"devices":[{"mac":"aa:bb:cc:dd:ee:ff","mcs":5,"ss":1,"rssi":-45,"channel":6,"bandwidth":0,"frames":500,"retries":2,"phy_rate_kbps":68800}]}

Quick reference

Method	When to use	Laptop command
Serial	Monitor mode, USB only	python3 tools/sdcard_recv.py -p /dev/ttyUSB0 -f fiwi-telemetry -o out.json
Beacon	Device on LAN, discover	python3 tools/beacon_listen.py --download --output-dir ./telemetry
HTTP	Device on LAN, known IP	curl -o out.json "http://<ip>:8080/sdcard/fiwi-telemetry"