# 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"`                     |