feat: update led-driver app files over ESP-NOW
tools/driver_ota.py (make ota-drivers) pushes the driver's .py files through the controller, one file per POST /drivers/ota/file. Drivers skip files they already have, and the rest are committed together. - one target: acked unicast, two chunks in flight - several targets: each file is broadcast once, then each driver is asked for its missing chunks and repaired by unicast - rel: rel_send_seq, rel_wait and rel_send_wait, plus a callback for the drivers' 0x26 status replies - commands are retried, because status replies are not acked - broadcast chunks are paced 50 ms apart: faster broadcast left C3 drivers unable to receive until reset - bench results in docs/BENCH_TEST.md, endpoints in docs/API.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
1c222771a5
commit
32c0ecfa76
13 files changed
+862
-9
No files matched your search
+10
@@ -64,6 +64,16 @@ Wi-Fi devices are not targeted by `/ws` directly; use **`POST /presets/send`**,
|
||||
|
||||
Below, `<id>` values are string identifiers used by the JSON stores (numeric strings in practice).
|
||||
|
||||
### Driver app update over ESP-NOW — `/drivers/ota` (v2 controller)
|
||||
|
||||
Pushes led-driver `.py` files to ESP-NOW drivers, one file per request. `tools/driver_ota.py` (or `make ota-drivers`) runs a whole session. The wire format is described in `led-driver/src/espnow_ota.py`. Only one request runs at a time; a second one gets `409`.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| POST | `/drivers/ota/file?mac=<macs>&sess=<n>&path=<p>&sha=<64 hex>` | Body: the raw file (0 to 65536 bytes). `mac` is a comma-separated list of 12-hex MACs, or `all` for every ESP-NOW device. `sess` is 1–65535 and is shared by all files of one update. `path` is the device path: a root file, `patterns/…` or `lib/…`. Drivers that already have a file with that sha256 skip it. With one target the chunks go by acked unicast. With several, the file is broadcast once, then each driver is asked for its missing chunks and repaired. The file is staged as `<path>.new` until commit. Reply: `{"<mac>":{"result":"same"\|"written"\|"error","code":"…","repaired":n}}`. Error codes come from the driver (`badhash`, `badpath`, `ioerr`, `toobig`, `incomplete`, `nosess`) or the link (`no reply to begin`, `link lost`, …). |
|
||||
| POST | `/drivers/ota/commit?mac=<macs>&sess=<n>` | Each driver moves its staged files into place, updates `file_hashes.json` and resets if anything changed. Reply: `{"<mac>":{"result":"ok"\|"error"}}`. |
|
||||
| POST | `/drivers/ota/abort?mac=<macs>&sess=<n>` | Each driver deletes its staged files. |
|
||||
|
||||
### Settings — `/settings`
|
||||
|
||||
| Method | Path | Description |
|
||||
|
||||
+38
-2
@@ -272,9 +272,45 @@ Groups: the controller sends a driver its group list when the driver announces i
|
||||
|
||||
**Wi-Fi start-up order on the C3.** With the extra link code loaded before Wi-Fi start-up, the C3 failed with `Wifi Unknown Error 0x0101` on about every other cold boot (2 of 4). Starting ESP-NOW before the pattern library and the LED driver claim memory fixed it (6 of 6 boots). `led-driver/src/main.py` now does this.
|
||||
|
||||
## 8. Troubleshooting
|
||||
## 8. Driver app update over ESP-NOW
|
||||
|
||||
Pushes the led-driver `.py` files from the PC, through the controller, to the drivers. The drivers need `espnow_ota.py` first, so install the code once over USB (`led-cli -p <port> --all`). After that:
|
||||
|
||||
```bash
|
||||
python3 tools/driver_ota.py $S3 --mac <mac> --dry-run # list the files and drivers, send nothing
|
||||
python3 tools/driver_ota.py $S3 --mac <mac> # one driver
|
||||
make ota-drivers HOST=$S3 BROADCAST=1 # every ESP-NOW driver, one broadcast and repairs
|
||||
```
|
||||
|
||||
Each file prints `written`, or nothing when the driver already has it. Drivers that received files reset after the commit, and the script waits for them to ack the link again. `--bad-sha <device path>` sends a wrong hash for one file, to test the abort path.
|
||||
|
||||
| Check | Expected |
|
||||
|---|---|
|
||||
| Push with nothing changed | every file skipped, no reset |
|
||||
| Edit one pattern, push | only that file written; the driver resets, comes back and runs the new code; `file_hashes.json` has the new hash |
|
||||
| `--bad-sha patterns/<file>.py` | `ERROR badhash` and `aborted:`; no `.new` files left on the driver and the old file unchanged |
|
||||
| Controller loss at 20% (`beats: false`) | still completes, slower, with `+n repaired` on some files |
|
||||
| `--broadcast` with two or more drivers | each changed file is sent once to all of them; afterwards every driver still acks and fires beats |
|
||||
|
||||
### Results of the first run (S3 controller, two C3 drivers with 119 LEDs, channel 5)
|
||||
|
||||
| | result |
|
||||
|---|---|
|
||||
| 62 files, nothing changed | all skipped in about 7 s (about 110 ms per file, mostly the driver hashing its copy), no reset |
|
||||
| One changed pattern (7.3 KB) | written and committed; driver reset and acked again; content and manifest checked over USB |
|
||||
| 60 KB file, unicast | 4.6 s, 12.8 KB/s including both hash checks |
|
||||
| 60 KB file, unicast, 20% controller loss | 4 of 4 runs completed, 3.8 to 8.3 KB/s |
|
||||
| Wrong hash | `badhash`, aborted, nothing staged or committed |
|
||||
| 60 KB file, broadcast to both | 4.2 s, about 14 KB/s per driver (29 KB/s in total), usually no repairs (once 3) |
|
||||
| 60 KB file, broadcast to both, 20% loss | 2 of 2 completed in about 33 s; 33 to 58 of the 65 chunks needed a repair (each chunk is 4 frames with no radio retries) |
|
||||
| Beat echo round trip after the change to `esp.irq()`, 177 beats, two drivers | 2.4 / 5.5 / 23.5 ms (min / avg / max) beyond the 30 ms lead, against 9.8 / 15.0 / 25.7 ms when the driver polled; 176 of 177 echoed |
|
||||
|
||||
**Broadcast pacing.** With 12 ms between broadcast chunks (about 30 KB/s) the drivers stopped receiving ESP-NOW frames altogether. Their `esp.stats()` receive count froze, with no drops counted, while the controller's unicasts were still acked by the drivers' radios. It lasted until a reset, more than 5 minutes once, and beats stopped too. The likely cause is the C3 writing to flash while the frames keep coming. At 50 ms (`BCAST_GAP_MS` in `main/drv_ota.c`) it did not happen in 5 runs.
|
||||
|
||||
## 9. Troubleshooting
|
||||
|
||||
- **A board on a USB-serial/JTAG port (C3, and the S3 controller) resets whenever a program opens its port,** and a C3 can land in ROM download mode (`wait usb download`). The old apt `mpremote` 0.4.0 hangs on this. Use the newer one in `~/projects/micropython/micropython/tools/mpremote/mpremote.py`, or `led-tool`, and note that `fs cp -r` fails on drivers that print timestamps (copy named files instead).
|
||||
- **Only one program can use a board's serial port at a time.** A serial logger left running while `led-cli` uploads corrupts the transfer silently: `led-cli` reports the files uploaded, but the old ones stay on the driver.
|
||||
- **Running a long `mpremote exec` on the driver resets it:** the driver's watchdog (10 s) keeps running after `mpremote` interrupts `main.py`, so keep REPL experiments under about 8 s and reset the driver afterwards.
|
||||
|
||||
- **Driver never reacts, no acks:** channel mismatch. Check `CONFIG_ESPNOW_CHANNEL` against the driver's `wifi_channel`. Neighbouring channels can still work at bench range, so a working link does not prove they match.
|
||||
@@ -284,7 +320,7 @@ Groups: the controller sends a driver its group list when the driver announces i
|
||||
- **Resync never triggers:** the driver ignores a digest equal to its own version; confirm with `/status` that `link.ver` changed after the missed play.
|
||||
- **Web UI is blank:** the web UI was not packed before the build; run `tools/build_web.sh` and build again (`make build` does this).
|
||||
|
||||
## 9. Cleanup
|
||||
## 10. Cleanup
|
||||
|
||||
```bash
|
||||
curl -s -X POST -d '{"percent":0}' http://$S3/test/loss
|
||||
|
||||
Reference in new issue
Block a user