feat(bridge): add wifi/serial bridge runtime and UI

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/API.md

@@ -3,7 +3,7 @@
 This document covers:
 
 1. **HTTP and WebSocket** exposed by the Raspberry Pi app (`src/main.py`) — profiles, zones, presets, transport send, pattern OTA helpers, and related resources.
-2. **LED driver JSON** — the compact **v1** message format. It is sent over the **serial → ESP-NOW bridge** to ESP32 peers and as **single JSON text messages** over the **outbound WebSocket** to **Wi-Fi** drivers (same logical fields).
+2. **LED driver JSON** — the compact **v1** message format. It is sent over the **ESP-NOW bridge** (WebSocket) to ESP32 peers and as **single JSON text messages** over the **outbound WebSocket** to **Wi-Fi** drivers (same logical fields).
 
 Default HTTP listen address: `0.0.0.0`. Port defaults to **80**; override with the **`PORT`** environment variable (see `pipenv run run`).
 
@@ -52,7 +52,7 @@ Profiles are selected with **`POST /profiles/<id>/apply`**, which sets `current_
 
 Connect to **`ws://<host>:<port>/ws`**.
 
-- Send **JSON**: the object is forwarded through the **serial sender** (6-byte MAC prefix + payload to the ESP-NOW bridge). Optional key **`to`**: 12-character hex MAC address; if present it is removed from the object and the payload is sent to that peer; otherwise the default destination from settings is used.
+- Send **JSON**: the object is forwarded through the **ESP-NOW bridge** (devices envelope or legacy MAC-prefixed payload). Optional key **`to`**: 12-character hex MAC address; if present it is removed from the object and the payload is sent to that peer; otherwise the default destination from settings is used.
 - Send **non-JSON text**: forwarded as raw bytes with the default address.
 - On send failure, the server may reply with `{"error": "Send failed"}`.
 

docs/espnow-architecture.md

@@ -19,11 +19,11 @@ Configure the Pi in `settings.json`:
 ```json
 {
   "bridge_ws_url": "ws://192.168.4.1/ws",
-  "wifi_channel": 6
+  "wifi_channel": 5
 }
 ```
 
-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).
+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**: set `wifi_channel` in the bridge and each led-driver `/settings.json` (applied at boot on those devices). The Pi stores `wifi_channel` in its own `settings.json` for alignment (restart led-controller after changing).
 
 ---
 

docs/espnow-binary-protocol.md

@@ -20,6 +20,8 @@ All ESP-NOW datagrams and Pi↔bridge WebSocket frames use **binary only** (no J
 | `0x02` | `GROUPS` | Controller → driver |
 | `0x03` | `CMD` | Controller → driver |
 | `0x04` | `GROUP_CMD` | Controller → broadcast |
+| `0x05` | `PING_REQ` | Controller → broadcast |
+| `0x06` | `PING_RSP` | Driver → controller (unicast) |
 | `0x10` | `BRIDGE_CH` | Controller → broadcast |
 
 ### ANNOUNCE (`0x01`)
@@ -57,6 +59,24 @@ Bytes 2… are a **v2 binary envelope** (see `src/util/binary_envelope.py`): 5-b
 
 Drivers apply the nested envelope only if `group_id` is in their stored group list.
 
+### PING_REQ (`0x05`)
+
+Controller discovery ping (broadcast). Drivers reply with **PING_RSP** after a random delay (50–500 ms) to reduce ESP-NOW collisions.
+
+| Field | Type |
+|-------|------|
+| ping_id | u32 LE |
+
+### PING_RSP (`0x06`)
+
+Unicast to the bridge/controller peer that sent the request (ESP-NOW source MAC of the received **PING_REQ**).
+
+| Field | Type |
+|-------|------|
+| ping_id | u32 LE |
+| name_len | u8 |
+| name | UTF-8 |
+
 ### BRIDGE_CH (`0x10`)
 
 | Field | Type |

docs/help.md

@@ -1,6 +1,6 @@
 # LED controller — user guide
 
-This page describes the **main web UI** served from the Raspberry Pi app: profiles, **zones**, presets, colour palettes, and sending commands to LED devices. Traffic may go over the **serial → ESP-NOW bridge** or **Wi-Fi** (TCP to drivers on the LAN), depending on each device’s transport.
+This page describes the **main web UI** served from the Raspberry Pi app: profiles, **zones**, presets, colour palettes, and sending commands to LED devices. Traffic may go over the **ESP-NOW bridge** (WebSocket) or **Wi-Fi** (TCP to drivers on the LAN), depending on each device’s transport.
 
 For HTTP routes and the wire format the driver expects, see **[API.md](API.md)**. For running the app locally, see the project **README**.