99 lines
3.7 KiB
Markdown
99 lines
3.7 KiB
Markdown
# 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](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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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):
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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"` |
|