From 07b328351856ef370785bc43d95187dfa5183dd2 Mon Sep 17 00:00:00 2001
From: Robert McMahon <rjmcmahon@rjmcmahon.com>
Date: Sat, 7 Feb 2026 12:31:47 -0800
Subject: [PATCH] Add doc/TELEMETRY_CAPTURE.md: how to enable and capture
 telemetry

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 doc/TELEMETRY_CAPTURE.md | 100 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 doc/TELEMETRY_CAPTURE.md

diff --git a/doc/TELEMETRY_CAPTURE.md b/doc/TELEMETRY_CAPTURE.md
new file mode 100644
index 0000000..688e1b4
--- /dev/null
+++ b/doc/TELEMETRY_CAPTURE.md
@@ -0,0 +1,100 @@
+# 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** to capture telemetry in this case. To capture over **WiFi**, run `monitor stop` first so the device rejoins the network, then download the telemetry file.
+
+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 (device on network)
+
+Use when the device is in STA mode and connected to the same LAN as the laptop. The device advertises itself via UDP broadcast on port 5555.
+
+**1. On the device:** Run `monitor stop` so it reconnects to WiFi. Telemetry is already on the SD card from when monitor mode was running.
+
+**2. 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"`                     |