feat(espnow): Pi bridge client, binary wire, and espnow-sender firmware

Replace serial/Wi-Fi driver transport paths with WebSocket bridge client, binary espnow_wire delivery, device announce registry, and restructured espnow-sender (AP + broadcast passthrough). Includes docs and tests. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-23 22:44:44 +12:00
parent f4ef85c182
commit 4fc3f46866
42 changed files with 4167 additions and 848 deletions
--- a/docs/espnow-architecture.md
+++ b/docs/espnow-architecture.md
@@ -0,0 +1,162 @@
+# ESP-NOW transport architecture
+
+This document describes how **led-controller**, the **bridge ESP32**, and **led-driver** devices work together. Wire-level byte layouts are in [espnow-binary-protocol.md](espnow-binary-protocol.md).
+
+**On the wire:** binary only (no JSON) for ESP-NOW and Pi↔bridge WebSocket. The Pi web UI and `db/*.json` still use JSON internally.
+
+## System overview
+
+![Three-node ESP-NOW architecture](images/espnow/system-overview.svg)
+
+| Component | Firmware / path | Role |
+|-----------|-----------------|------|
+| **led-controller** | Raspberry Pi, `src/` | Web app; WebSocket **client** to bridge; device registry; builds binary commands |
+| **Bridge** | [`espnow-sender/`](../espnow-sender/) | WebSocket **server** `/ws`; relays binary ↔ ESP-NOW; max **20** peers (LRU) |
+| **led-driver** | [`led-driver/`](../led-driver/) submodule | Boot **ANNOUNCE** broadcast; applies **GROUPS**, **CMD**, **GROUP_CMD** |
+
+Configure the Pi in `settings.json`:
+
+```json
+{
+  "bridge_ws_url": "ws://192.168.4.1/ws",
+  "wifi_channel": 6
+}
+```
+
+Connect the Pi to the **bridge access point** (SSID = bridge `name` in `/settings.json`, default IP **192.168.4.1**). All nodes must use the same 2.4 GHz **channel** (Pi sends `BRIDGE_CH` on connect; bridge updates AP + ESP-NOW STA).
+
+---
+
+## Boot and registration
+
+![Boot and registration sequence](images/espnow/boot-sequence.svg)
+
+1. Driver powers on and sends **ANNOUNCE** to broadcast MAC `ff:ff:ff:ff:ff:ff`.
+2. Bridge receives it and forwards a **WebSocket uplink** frame to the Pi (peer MAC + packet).
+3. Pi **upserts** the device in `db/device.json` (key = 12-char hex MAC).
+4. Pi scans `db/group.json` and builds a **GROUPS** packet.
+5. Pi sends **GROUPS** unicast to that MAC via the bridge.
+6. Driver stores group ids in RAM for **GROUP_CMD** filtering.
+
+If the Pi or bridge is not up yet, the driver re-sends **ANNOUNCE** periodically until **GROUPS** arrives.
+
+---
+
+## Sending presets and commands
+
+![Command delivery flow](images/espnow/command-flow.svg)
+
+1. UI or API triggers a send (e.g. `POST /presets/send`).
+2. Pi builds one or more **CMD** packets (v2 binary envelope, chunked to ≤250 bytes).
+3. Each packet is wrapped in a **WebSocket downlink** frame (unicast MAC or broadcast).
+4. Bridge forwards on ESP-NOW.
+5. Driver parses and applies (presets, select, brightness, device_config, etc.).
+
+For a **group**, Pi may send **GROUP_CMD** on broadcast once per chunk; only drivers that belong to that group apply the payload.
+
+---
+
+## Packet layers
+
+![Packet layer stack](images/espnow/packet-layers.svg)
+
+### Layer A — WebSocket frame (Pi ↔ bridge)
+
+| Offset | Size | Field |
+|--------|------|--------|
+| 0 | 1 | `flags` — bit0 = broadcast (`ff:ff:…`); peer ignored if set |
+| 1 | 6 | `peer` — destination MAC (raw bytes) |
+| 7 | … | Full ESP-NOW packet (layer B) |
+
+**Uplink** (bridge → Pi): same layout; `flags = 0`, `peer` = sender.
+
+**Ack** (bridge → Pi after downlink): 1 byte — `0x01` ok, `0x00` error.
+
+### Layer B — ESP-NOW packet (on air)
+
+| Offset | Size | Field |
+|--------|------|--------|
+| 0 | 1 | Magic `0x4C` (`'L'`) |
+| 1 | 1 | Message type |
+| 2 | … | Body (≤248 bytes so total ≤250) |
+
+![Message types](images/espnow/message-types.svg)
+
+| Type | Value | Direction | Purpose |
+|------|-------|-------------|---------|
+| ANNOUNCE | `0x01` | Driver → broadcast | Boot settings |
+| GROUPS | `0x02` | Pi → driver | Group membership |
+| CMD | `0x03` | Pi → driver | Command (v2 envelope) |
+| GROUP_CMD | `0x04` | Pi → broadcast | Command scoped to one group |
+| BRIDGE_CH | `0x10` | Pi → bridge | Set STA channel 1–11 |
+
+### Layer C — v2 command envelope (inside CMD / GROUP_CMD)
+
+Used for presets, select, default, brightness. **No JSON.**
+
+| Byte | Field |
+|------|--------|
+| 0 | Version `2` |
+| 1 | Brightness wire 0–127 (→ 0–255); `128–255` = unchanged |
+| 2 | `lp` — presets section length |
+| 3 | `ls` — select section length |
+| 4 | `ld` — default section length |
+| 5… | Presets blob (`lp` bytes) |
+| … | Select blob (`ls` bytes) |
+| … | Default blob (`ld` bytes) |
+
+Optional trailing `0x01` after the envelope in **CMD** means `save` (persist to flash).
+
+Implementation: [`src/util/binary_envelope.py`](../src/util/binary_envelope.py), [`src/util/espnow_wire.py`](../src/util/espnow_wire.py).
+
+---
+
+## Message body reference
+
+### ANNOUNCE (`0x01`)
+
+Sender MAC comes from ESP-NOW headers, not the body.
+
+```
+name_len (u8) | name (utf-8) | num_leds (u16 LE) | color_order (u8) | startup_mode (u8) | brightness (u8) | device_type (u8)
+```
+
+| `color_order` | `startup_mode` |
+|---------------|----------------|
+| 0=rgb, 1=rbg, 2=grb, 3=gbr, 4=brg, 5=bgr | 0=default, 1=last, 2=off |
+
+### GROUPS (`0x02`)
+
+```
+count (u8) | repeat: id_len (u8) | group_id (utf-8)
+```
+
+Group ids match keys in `db/group.json` (e.g. `"5"`, `"18"`).
+
+### GROUP_CMD (`0x04`)
+
+```
+group_id_len (u8) | group_id (utf-8) | v2 envelope | [optional 0x01 save]
+```
+
+Driver applies only if `group_id` is in its stored list.
+
+---
+
+## Size limits and chunking
+
+- **250 bytes** max per ESP-NOW datagram.
+- Large preset libraries → multiple **CMD** packets from the Pi.
+- Bridge stores at most **20** peer MACs; oldest peer evicted (LRU) when full.
+
+---
+
+## Related files
+
+| Topic | Location |
+|-------|----------|
+| Byte-level spec | [espnow-binary-protocol.md](espnow-binary-protocol.md) |
+| Pi wire codec | [`src/util/espnow_wire.py`](../src/util/espnow_wire.py) |
+| Pi bridge client | [`src/models/bridge_ws_client.py`](../src/models/bridge_ws_client.py) |
+| Bridge firmware | [`espnow-sender/main.py`](../espnow-sender/main.py) |
+| Driver ESP-NOW | [`led-driver/src/espnow_transport.py`](../led-driver/src/espnow_transport.py) |
--- a/docs/espnow-binary-protocol.md
+++ b/docs/espnow-binary-protocol.md
@@ -0,0 +1,94 @@
+# ESP-NOW binary protocol
+
+**See also:** [espnow-architecture.md](espnow-architecture.md) (diagrams, flows, configuration).
+
+All ESP-NOW datagrams and Pi↔bridge WebSocket frames use **binary only** (no JSON on the wire). Maximum ESP-NOW payload length: **250 bytes**.
+
+## ESP-NOW packet
+
+| Offset | Field |
+|--------|--------|
+| 0 | Magic `0x4C` (`'L'`) |
+| 1 | Message type |
+| 2… | Type-specific body |
+
+### Message types
+
+| Value | Name | Direction |
+|-------|------|-----------|
+| `0x01` | `ANNOUNCE` | Driver → broadcast |
+| `0x02` | `GROUPS` | Controller → driver |
+| `0x03` | `CMD` | Controller → driver |
+| `0x04` | `GROUP_CMD` | Controller → broadcast |
+| `0x10` | `BRIDGE_CH` | Controller → broadcast |
+
+### ANNOUNCE (`0x01`)
+
+Driver settings at boot. Sender MAC is taken from the ESP-NOW peer address (not repeated in the body).
+
+| Field | Type |
+|-------|------|
+| name_len | u8 |
+| name | UTF-8 |
+| num_leds | u16 LE |
+| color_order | u8 enum: 0=rgb, 1=rbg, 2=grb, 3=gbr, 4=brg, 5=bgr |
+| startup_mode | u8: 0=default, 1=last, 2=off |
+| brightness | u8 0–255 |
+| device_type | u8: 0=led |
+
+### GROUPS (`0x02`)
+
+| Field | Type |
+|-------|------|
+| count | u8 |
+| × count | u8 id_len + UTF-8 group id |
+
+### CMD (`0x03`)
+
+Bytes 2… are a **v2 binary envelope** (see `src/util/binary_envelope.py`): 5-byte header + presets/select/default blobs. Total packet ≤ 250 bytes.
+
+### GROUP_CMD (`0x04`)
+
+| Field | Type |
+|-------|------|
+| group_id_len | u8 |
+| group_id | UTF-8 |
+| cmd_envelope | v2 binary envelope |
+
+Drivers apply the nested envelope only if `group_id` is in their stored group list.
+
+### BRIDGE_CH (`0x10`)
+
+| Field | Type |
+|-------|------|
+| channel | u8 (1–11) |
+
+Sets the bridge ESP32 STA channel (not forwarded to LED drivers as a command).
+
+## Pi ↔ bridge WebSocket frame
+
+Binary WebSocket messages only.
+
+| Offset | Field |
+|--------|--------|
+| 0 | flags: bit0 = broadcast destination; bit1 reserved |
+| 1–6 | peer MAC (6 bytes); ignored if broadcast |
+| 7… | ESP-NOW packet (magic + type + body) |
+
+Broadcast destination uses peer `ff:ff:ff:ff:ff:ff`.
+
+The bridge maintains at most **20** ESP-NOW peers (LRU eviction).
+
+## v2 command envelope
+
+Native binary sections (no JSON). Header:
+
+| Byte | Meaning |
+|------|---------|
+| 0 | Version `2` |
+| 1 | Brightness wire 0–127 (maps to 0–255); 128–255 = unchanged |
+| 2 | Presets section length |
+| 3 | Select section length |
+| 4 | Default section length |
+
+See `binary_envelope.py` for blob layouts.
--- a/docs/images/espnow/boot-sequence.svg
+++ b/docs/images/espnow/boot-sequence.svg
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 780 520" font-family="system-ui, Segoe UI, sans-serif">
+  <defs>
+    <marker id="arr" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+      <path d="M0,0 L6,3 L0,6 Z" fill="#333"/>
+    </marker>
+    <style>
+      .actor { fill: #f4f6f8; stroke: #2c3e50; stroke-width: 2; }
+      .lifeline { stroke: #aaa; stroke-width: 1; stroke-dasharray: 4 4; }
+      .msg { stroke: #2980b9; stroke-width: 1.5; fill: none; marker-end: url(#arr); }
+      .msgret { stroke: #27ae60; stroke-width: 1.5; fill: none; marker-end: url(#arr); }
+      .note { fill: #fef9e7; stroke: #d4ac0d; stroke-width: 1; }
+      .t { font-size: 13px; fill: #222; }
+      .h { font-size: 14px; font-weight: 700; fill: #111; }
+      .s { font-size: 11px; fill: #555; }
+    </style>
+  </defs>
+  <text x="390" y="24" text-anchor="middle" class="h" font-size="16">Boot and registration sequence</text>
+
+  <!-- Actors -->
+  <rect class="actor" x="40" y="40" width="120" height="40" rx="6"/>
+  <text x="100" y="66" text-anchor="middle" class="h">Driver</text>
+  <line class="lifeline" x1="100" y1="80" x2="100" y2="480"/>
+
+  <rect class="actor" x="310" y="40" width="120" height="40" rx="6"/>
+  <text x="370" y="66" text-anchor="middle" class="h">Bridge</text>
+  <line class="lifeline" x1="370" y1="80" x2="370" y2="480"/>
+
+  <rect class="actor" x="580" y="40" width="140" height="40" rx="6"/>
+  <text x="650" y="66" text-anchor="middle" class="h">led-controller</text>
+  <line class="lifeline" x1="650" y1="80" x2="650" y2="480"/>
+
+  <!-- Messages -->
+  <path class="msg" d="M 100 110 L 368 110"/>
+  <text x="234" y="102" text-anchor="middle" class="t">ESP-NOW broadcast ANNOUNCE</text>
+  <text x="234" y="128" text-anchor="middle" class="s">dest ff:ff:ff:ff:ff:ff</text>
+
+  <path class="msg" d="M 372 150 L 648 150"/>
+  <text x="510" y="142" text-anchor="middle" class="t">WS uplink: peer MAC + packet</text>
+
+  <rect class="note" x="520" y="168" width="200" height="44" rx="4"/>
+  <text x="620" y="188" text-anchor="middle" class="s">upsert device in</text>
+  <text x="620" y="204" text-anchor="middle" class="s">db/device.json</text>
+
+  <path class="msgret" d="M 648 230 L 372 230"/>
+  <text x="510" y="222" text-anchor="middle" class="t">WS downlink: GROUPS unicast</text>
+
+  <path class="msgret" d="M 368 270 L 102 270"/>
+  <text x="234" y="262" text-anchor="middle" class="t">ESP-NOW unicast GROUPS</text>
+
+  <rect class="note" x="30" y="300" width="140" height="40" rx="4"/>
+  <text x="100" y="318" text-anchor="middle" class="s">store group ids</text>
+  <text x="100" y="332" text-anchor="middle" class="s">in RAM</text>
+
+  <text x="390" y="380" text-anchor="middle" class="s">Driver re-sends ANNOUNCE until GROUPS received if Pi/bridge late</text>
+  <text x="390" y="460" text-anchor="middle" class="s">ANNOUNCE body: name, num_leds, color_order, startup_mode, brightness</text>
+</svg>
--- a/docs/images/espnow/command-flow.svg
+++ b/docs/images/espnow/command-flow.svg
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 780 480" font-family="system-ui, Segoe UI, sans-serif">
+  <defs>
+    <marker id="a" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+      <path d="M0,0 L6,3 L0,6 Z" fill="#333"/>
+    </marker>
+    <style>
+      .actor { fill: #f4f6f8; stroke: #2c3e50; stroke-width: 2; }
+      .lifeline { stroke: #aaa; stroke-width: 1; stroke-dasharray: 4 4; }
+      .msg { stroke: #8e44ad; stroke-width: 1.5; fill: none; marker-end: url(#a); }
+      .t { font-size: 13px; fill: #222; }
+      .h { font-size: 14px; font-weight: 700; }
+      .s { font-size: 11px; fill: #555; }
+    </style>
+  </defs>
+  <text x="390" y="24" text-anchor="middle" class="h" font-size="16">Preset / command delivery</text>
+
+  <rect class="actor" x="30" y="44" width="90" height="36" rx="6"/>
+  <text x="75" y="68" text-anchor="middle" class="h">UI</text>
+  <line class="lifeline" x1="75" y1="80" x2="75" y2="440"/>
+
+  <rect class="actor" x="200" y="44" width="120" height="36" rx="6"/>
+  <text x="260" y="68" text-anchor="middle" class="h">Pi</text>
+  <line class="lifeline" x1="260" y1="80" x2="260" y2="440"/>
+
+  <rect class="actor" x="400" y="44" width="100" height="36" rx="6"/>
+  <text x="450" y="68" text-anchor="middle" class="h">Bridge</text>
+  <line class="lifeline" x1="450" y1="80" x2="450" y2="440"/>
+
+  <rect class="actor" x="580" y="44" width="100" height="36" rx="6"/>
+  <text x="630" y="68" text-anchor="middle" class="h">Driver</text>
+  <line class="lifeline" x1="630" y1="80" x2="630" y2="440"/>
+
+  <path class="msg" d="M 77 110 L 258 110"/>
+  <text x="168" y="102" text-anchor="middle" class="t">POST /presets/send (JSON)</text>
+
+  <text x="260" y="145" text-anchor="middle" class="s">build v2 envelope</text>
+  <text x="260" y="162" text-anchor="middle" class="s">pack CMD (d250 B)</text>
+
+  <path class="msg" d="M 262 190 L 448 190"/>
+  <text x="355" y="182" text-anchor="middle" class="t">WS downlink + CMD</text>
+
+  <path class="msg" d="M 452 230 L 628 230"/>
+  <text x="540" y="222" text-anchor="middle" class="t">ESP-NOW unicast / broadcast</text>
+
+  <text x="630" y="275" text-anchor="middle" class="s">parse CMD</text>
+  <text x="630" y="292" text-anchor="middle" class="s">apply presets / select</text>
+
+  <rect x="140" y="320" width="500" height="90" fill="#f0f0f0" stroke="#999" rx="6"/>
+  <text x="390" y="345" text-anchor="middle" class="t">GROUP_CMD: one broadcast per group id  only members apply</text>
+  <text x="390" y="368" text-anchor="middle" class="s">Large libraries ’ multiple CMD chunks from Pi</text>
+  <text x="390" y="390" text-anchor="middle" class="s">Optional trailing 0x01 on CMD = save to flash</text>
+</svg>
--- a/docs/images/espnow/message-types.svg
+++ b/docs/images/espnow/message-types.svg
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 320" font-family="system-ui, Segoe UI, sans-serif">
+  <text x="320" y="28" text-anchor="middle" font-size="16" font-weight="700" fill="#111">ESP-NOW message types (byte 1 after 0x4C)</text>
+
+  <rect fill="#2c3e50" x="40" y="48" width="560" height="28" rx="4"/>
+  <text x="70" y="67" fill="#fff" font-size="12" font-weight="600">Value</text>
+  <text x="150" y="67" fill="#fff" font-size="12" font-weight="600">Name</text>
+  <text x="280" y="67" fill="#fff" font-size="12" font-weight="600">Direction</text>
+  <text x="460" y="67" fill="#fff" font-size="12" font-weight="600">Purpose</text>
+
+  <rect fill="#fff" stroke="#ddd" x="40" y="76" width="560" height="32"/>
+  <text x="70" y="97" font-size="12">0x01</text>
+  <text x="150" y="97" font-size="12" font-weight="600">ANNOUNCE</text>
+  <text x="280" y="97" font-size="12">Driver ? broadcast</text>
+  <text x="460" y="97" font-size="12">Boot settings</text>
+
+  <rect fill="#f8f9fa" stroke="#ddd" x="40" y="108" width="560" height="32"/>
+  <text x="70" y="129" font-size="12">0x02</text>
+  <text x="150" y="129" font-size="12" font-weight="600">GROUPS</text>
+  <text x="280" y="129" font-size="12">Pi ? driver</text>
+  <text x="460" y="129" font-size="12">Group membership</text>
+
+  <rect fill="#fff" stroke="#ddd" x="40" y="140" width="560" height="32"/>
+  <text x="70" y="161" font-size="12">0x03</text>
+  <text x="150" y="161" font-size="12" font-weight="600">CMD</text>
+  <text x="280" y="161" font-size="12">Pi ? driver</text>
+  <text x="460" y="161" font-size="12">v2 command envelope</text>
+
+  <rect fill="#f8f9fa" stroke="#ddd" x="40" y="172" width="560" height="32"/>
+  <text x="70" y="193" font-size="12">0x04</text>
+  <text x="150" y="193" font-size="12" font-weight="600">GROUP_CMD</text>
+  <text x="280" y="193" font-size="12">Pi ? broadcast</text>
+  <text x="460" y="193" font-size="12">Filtered by group id</text>
+
+  <rect fill="#fff" stroke="#ddd" x="40" y="204" width="560" height="32"/>
+  <text x="70" y="225" font-size="12">0x10</text>
+  <text x="150" y="225" font-size="12" font-weight="600">BRIDGE_CH</text>
+  <text x="280" y="225" font-size="12">Pi ? bridge</text>
+  <text x="460" y="225" font-size="12">Wi-Fi channel 1–11</text>
+
+  <text x="320" y="270" text-anchor="middle" font-size="12" fill="#555">Every packet: [0x4C magic][type][body…] total ? 250 bytes</text>
+</svg>
--- a/docs/images/espnow/packet-layers.svg
+++ b/docs/images/espnow/packet-layers.svg
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 480" font-family="ui-monospace, monospace">
+  <defs>
+    <style>
+      .layer { stroke: #2c3e50; stroke-width: 2; }
+      .ws { fill: #e8f4fc; }
+      .esp { fill: #fef9e7; }
+      .env { fill: #eafaf1; }
+      .lbl { font-family: system-ui, sans-serif; font-size: 14px; font-weight: 700; fill: #111; }
+      .byte { font-size: 12px; fill: #333; }
+      .title { font-family: system-ui, sans-serif; font-size: 17px; font-weight: 700; }
+    </style>
+  </defs>
+  <text x="360" y="28" text-anchor="middle" class="title">Packet layers (outside ’ inside)</text>
+
+  <!-- WS layer -->
+  <rect class="layer ws" x="60" y="50" width="600" height="70" rx="6"/>
+  <text x="80" y="78" class="lbl">WebSocket frame (Pi ” bridge)</text>
+  <rect x="80" y="88" width="50" height="24" fill="#fff" stroke="#666"/>
+  <text x="105" y="104" text-anchor="middle" class="byte">flags</text>
+  <rect x="138" y="88" width="120" height="24" fill="#fff" stroke="#666"/>
+  <text x="198" y="104" text-anchor="middle" class="byte">peer MAC ×6</text>
+  <rect x="268" y="88" width="380" height="24" fill="#fff" stroke="#666"/>
+  <text x="458" y="104" text-anchor="middle" class="byte">ESP-NOW packet (below)</text>
+
+  <!-- ESP layer -->
+  <rect class="layer esp" x="100" y="140" width="520" height="70" rx="6"/>
+  <text x="120" y="168" class="lbl">ESP-NOW datagram (d250 bytes)</text>
+  <rect x="120" y="178" width="40" height="24" fill="#fff" stroke="#666"/>
+  <text x="140" y="194" text-anchor="middle" class="byte">4C</text>
+  <rect x="168" y="178" width="50" height="24" fill="#fff" stroke="#666"/>
+  <text x="193" y="194" text-anchor="middle" class="byte">type</text>
+  <rect x="230" y="178" width="370" height="24" fill="#fff" stroke="#666"/>
+  <text x="415" y="194" text-anchor="middle" class="byte">body (ANNOUNCE / GROUPS / CMD / &)</text>
+
+  <!-- CMD + envelope -->
+  <rect class="layer env" x="140" y="230" width="440" height="120" rx="6"/>
+  <text x="160" y="258" class="lbl">Inside CMD (0x03)  v2 command envelope</text>
+  <rect x="160" y="268" width="28" height="22" fill="#fff" stroke="#666"/>
+  <text x="174" y="283" text-anchor="middle" class="byte">02</text>
+  <rect x="194" y="268" width="28" height="22" fill="#fff" stroke="#666"/>
+  <text x="208" y="283" text-anchor="middle" class="byte">br</text>
+  <rect x="228" y="268" width="28" height="22" fill="#fff" stroke="#666"/>
+  <text x="242" y="283" text-anchor="middle" class="byte">lp</text>
+  <rect x="262" y="268" width="28" height="22" fill="#fff" stroke="#666"/>
+  <text x="276" y="283" text-anchor="middle" class="byte">ls</text>
+  <rect x="296" y="268" width="28" height="22" fill="#fff" stroke="#666"/>
+  <text x="310" y="283" text-anchor="middle" class="byte">ld</text>
+  <rect x="334" y="268" width="110" height="22" fill="#fff" stroke="#666"/>
+  <text x="389" y="283" text-anchor="middle" class="byte">presets</text>
+  <rect x="450" y="268" width="60" height="22" fill="#fff" stroke="#666"/>
+  <text x="480" y="283" text-anchor="middle" class="byte">select</text>
+  <rect x="516" y="268" width="54" height="22" fill="#fff" stroke="#666"/>
+  <text x="543" y="283" text-anchor="middle" class="byte">def</text>
+  <rect x="160" y="300" width="60" height="22" fill="#ffeaa7" stroke="#666"/>
+  <text x="190" y="315" text-anchor="middle" class="byte">save?</text>
+  <text x="360" y="335" text-anchor="middle" class="byte" font-family="system-ui">optional 0x01 after envelope</text>
+
+  <text x="360" y="400" text-anchor="middle" font-family="system-ui" font-size="12" fill="#555">
+    Pi REST/UI uses JSON · conversion to binary happens at bridge boundary
+  </text>
+</svg>
--- a/docs/images/espnow/system-overview.svg
+++ b/docs/images/espnow/system-overview.svg
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 820 420" font-family="system-ui, Segoe UI, sans-serif">
+  <defs>
+    <marker id="arrow" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+      <path d="M0,0 L6,3 L0,6 Z" fill="#333"/>
+    </marker>
+    <style>
+      .box { fill: #f4f6f8; stroke: #2c3e50; stroke-width: 2; rx: 8; }
+      .title { font-size: 16px; font-weight: 700; fill: #1a1a1a; }
+      .label { font-size: 13px; fill: #333; }
+      .small { font-size: 11px; fill: #555; }
+      .line { stroke: #333; stroke-width: 1.5; fill: none; marker-end: url(#arrow); }
+      .dashed { stroke-dasharray: 6 4; }
+    </style>
+  </defs>
+  <text x="410" y="28" text-anchor="middle" class="title" font-size="18">ESP-NOW LED system  three nodes</text>
+
+  <!-- Pi -->
+  <rect class="box" x="40" y="60" width="220" height="300"/>
+  <text x="150" y="88" text-anchor="middle" class="title">led-controller</text>
+  <text x="150" y="108" text-anchor="middle" class="small">Raspberry Pi</text>
+  <rect x="60" y="125" width="180" height="36" fill="#fff" stroke="#888" rx="4"/>
+  <text x="150" y="148" text-anchor="middle" class="label">Web UI / REST (JSON)</text>
+  <rect x="60" y="170" width="180" height="36" fill="#fff" stroke="#888" rx="4"/>
+  <text x="150" y="193" text-anchor="middle" class="label">db/device.json, groups</text>
+  <rect x="60" y="215" width="180" height="36" fill="#e8f4fc" stroke="#2980b9" rx="4"/>
+  <text x="150" y="238" text-anchor="middle" class="label">espnow_wire + binary</text>
+  <rect x="60" y="260" width="180" height="36" fill="#e8f4fc" stroke="#2980b9" rx="4"/>
+  <text x="150" y="283" text-anchor="middle" class="label">bridge_ws_client</text>
+  <text x="150" y="330" text-anchor="middle" class="small">WS client ’ bridge</text>
+
+  <!-- Bridge -->
+  <rect class="box" x="300" y="100" width="220" height="220"/>
+  <text x="410" y="128" text-anchor="middle" class="title">Bridge ESP32</text>
+  <text x="410" y="148" text-anchor="middle" class="small">espnow-sender</text>
+  <rect x="320" y="165" width="180" height="36" fill="#fff" stroke="#888" rx="4"/>
+  <text x="410" y="188" text-anchor="middle" class="label">WebSocket server /ws</text>
+  <rect x="320" y="210" width="180" height="36" fill="#fef9e7" stroke="#d4ac0d" rx="4"/>
+  <text x="410" y="233" text-anchor="middle" class="label">ESP-NOW relay</text>
+  <text x="410" y="275" text-anchor="middle" class="small">max 20 peers (LRU)</text>
+
+  <!-- Drivers -->
+  <rect class="box" x="560" y="60" width="220" height="300"/>
+  <text x="670" y="88" text-anchor="middle" class="title">led-driver × N</text>
+  <text x="670" y="108" text-anchor="middle" class="small">ESP32 LED strips</text>
+  <rect x="580" y="140" width="180" height="32" fill="#eafaf1" stroke="#27ae60" rx="4"/>
+  <text x="670" y="161" text-anchor="middle" class="label">boot ANNOUNCE</text>
+  <rect x="580" y="182" width="180" height="32" fill="#fff" stroke="#888" rx="4"/>
+  <text x="670" y="203" text-anchor="middle" class="label">store GROUPS</text>
+  <rect x="580" y="224" width="180" height="32" fill="#fff" stroke="#888" rx="4"/>
+  <text x="670" y="245" text-anchor="middle" class="label">apply CMD / GROUP_CMD</text>
+  <text x="670" y="320" text-anchor="middle" class="small">binary only on air</text>
+
+  <!-- Arrows -->
+  <path class="line" d="M 260 278 L 298 200"/>
+  <text x="268" y="235" class="small">binary WS</text>
+  <path class="line" d="M 520 230 L 558 200"/>
+  <text x="528" y="218" class="small">ESP-NOW</text>
+  <path class="line dashed" d="M 520 260 L 558 280"/>
+  <text x="528" y="278" class="small">broadcast</text>
+  <path class="line dashed" d="M 558 160 L 520 175"/>
+  <text x="530" y="158" class="small">ANNOUNCE</text>
+
+  <text x="410" y="400" text-anchor="middle" class="small">d250 bytes per ESP-NOW frame · no JSON on wire</text>
+</svg>