chore(submodules): bump led-driver

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

.cursor/rules/commit.mdc

@@ -0,0 +1,26 @@
+---
+description: Git commit messages and how to split work into commits
+alwaysApply: true
+---
+
+# Commits
+
+When preparing commits (especially when the user asks to commit):
+
+1. **Prefer multiple commits** over one large commit when changes span distinct concerns (e.g. UI vs docs vs API). One logical unit per commit.
+2. **Message format:** `type(scope): short imperative subject` (lowercase subject after the colon; no trailing period).
+   - **Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf` (use what fits).
+   - **Scope:** optional but encouraged — e.g. `ui`, `api`, `profiles`, `presets`, `esp32`.
+3. **Subject line:** ~50 characters or less; describe *what* changed, not the ticket number alone.
+4. **Body:** only when needed (breaking change, non-obvious rationale, or multiple bullets). Otherwise subject is enough.
+
+**Examples**
+
+- `feat(ui): gate profile delete to edit mode`
+- `docs: document run vs edit in API`
+- `fix(api): resolve preset delete route argument clash`
+
+**Do not**
+
+- Squash unrelated fixes and doc tweaks into one commit unless the user explicitly wants a single commit.
+- Use vague messages like `update`, `fixes`, or `wip`.

.cursor/rules/led-driver.mdc

@@ -0,0 +1,45 @@
+---
+description: led-driver — MicroPython ESP32: mpremote, imports, layout, I/O, no pycache in src
+globs: led-driver/**
+alwaysApply: false
+---
+
+# led-driver (MicroPython / ESP32)
+
+## Device and tests
+
+1. Validate **MicroPython behaviour** under **`led-driver/`** with **`mpremote connect <PORT> …`** on the chip. Host **`python3`** does **not** prove the firmware build.
+
+2. **Execution target is fixed:** treat **`led-driver/`** code as firmware that runs **only on MicroPython ESP32 devices**. Do **not** run `led-driver/src/main.py` (or other firmware modules) with host CPython as a normal execution path.
+
+3. **Flow:** `mpremote connect <PORT> cp <local> :<on-flash>` then `run <script>.py`. Inline commands only — no **`.sh`** wrappers unless the user asks. Default serial placeholder: **`/dev/ttyACM0`**.
+
+4. Checks that **import and run** code from **`led-driver/src/`** belong in **`led-driver/tests/`** and run with **`mpremote run …`**. **Do not** add **`pytest`** under **`led-controller/tests/`** that **`sys.path`**-loads **`led-driver/src`** and runs those modules on CPython.
+
+## Import layout
+
+4. **No** **`sys.path.insert`**, **`__file__`** path stitching, or other import-path hacks under **`led-driver/`**. Use device flash search path, or host **`PYTHONPATH`** / layout you control.
+
+5. **No** “import fixer” code — fix copy order, flash paths, or env instead.
+
+## Imports (fail loudly)
+
+6. If a dependency does not load, **crash** and fix deployment or filesystem. **Do not** catch **`ImportError`** / **`ModuleNotFoundError`** around **`import`** / **`from … import`** for app/firmware modules (`settings`, `utils`, `network`, `machine`, …).
+
+7. **Allowed — stdlib name pairs only** (MicroPython vs CPython): one **`except ImportError`**, then **one** fallback import, **no** extra logic in **`except`**:
+   - `uos` → `os`
+   - `ubinascii` → `binascii`
+   - `utime` → `time`  
+   Not for “maybe the file exists on flash” — only different **stdlib** names.
+
+8. **No** large inline reimplementations after **`except ImportError`** — deploy the real module.
+
+## I/O
+
+9. Non-blocking **recv** / **accept**: use plain **`except OSError:`** (or **break** on empty). **No** errno / EAGAIN / EWOULDBLOCK tables or **`getattr(errno, …)`** unless fixing a **documented** target bug.
+
+10. Minimal **`try` / `except OSError`** around optional socket options (e.g. **`SO_REUSEADDR`**) is fine.
+
+## Host Python and `src/`
+
+11. **Do not** leave **`__pycache__/`** or **`.pyc`** under **`led-driver/src/`** from host runs. Remove if created; **`.gitignore`** already ignores it. Prefer **`PYTHONDONTWRITEBYTECODE=1`** or **`-B`** when host Python must touch **`led-driver/src/`**.

.cursor/rules/pattern-workflow.mdc

@@ -0,0 +1,14 @@
+---
+description: Require test pattern, pattern metadata, and test preset for new patterns
+alwaysApply: true
+---
+
+# Pattern workflow requirements
+
+1. When creating a new pattern under `led-driver/src/patterns/`, also add/update a corresponding test file in `led-driver/tests/patterns/`.
+
+2. When adding a new pattern, ensure led-controller has `db/pattern.json`; if it does not exist, create it. Add the new pattern metadata and parameter mappings there. Optionally set **`supports_manual`** to `false` when the pattern is a poor fit for manual mode or audio beat triggers (smooth/blended animations); omit or `true` otherwise.
+
+3. When adding a new pattern, add at least one test preset entry in `db/preset.json` in led-controller that uses the new pattern.
+
+4. For any pattern that supports both auto and manual modes, keep behaviour parity unless explicitly requested otherwise: background colour handling, colour-cycling order, and parameter timing semantics (e.g. `n2`/`n3` meaning) must match between auto and manual paths.

.cursor/rules/scoped-fixes.mdc

@@ -0,0 +1,18 @@
+---
+description: Fix only the issue or task the user gave; no refactors unless requested
+alwaysApply: true
+---
+
+# Scoped fixes (no overscoping)
+
+1. **Change only what is needed** to satisfy the user’s *current* request (bug, error, feature, or explicit follow-up). Prefer the smallest diff that fixes it.
+
+2. **Refactors:** Do **not** refactor (restructure, rename, extract functions, change abstractions, or “make it nicer”) **unless the user explicitly asked for a refactor**. A bug fix may touch nearby lines only as much as required to correct the bug.
+
+3. **Do not** rename, reformat, or “clean up” unrelated code; do not add extra error handling, logging, or features you were not asked for.
+
+4. **Related issues:** If you spot other problems (missing functions, wrong types elsewhere, style), you may **mention them in prose** — do **not** fix them unless the user explicitly asks.
+
+5. **Tests and docs:** Add or change tests or documentation **only** when the user asked for them or they are strictly required to verify the requested fix.
+
+6. **Multiple distinct fixes:** If the user reported one error (e.g. a single `TypeError`), fix **that** cause first. Offer to tackle follow-ups separately rather than bundling.

.cursor/rules/spelling.mdc

@@ -0,0 +1,10 @@
+---
+description: British spelling for user-facing text; technical identifiers stay as-is
+alwaysApply: true
+---
+
+# Spelling: colour
+
+- **User-facing strings** (Help modal, button labels, README prose, `docs/`, error messages shown in the UI): use **British English** — **colour**, **favour**, **behaviour**, etc., unless quoting existing product names.
+- **Do not rename** existing code for spelling: **identifiers**, file names, URL paths, JSON keys, CSS properties (`color`), HTML attributes (`type="color"`), and API field names stay as they are (`color`, `colors`, `palette`, etc.) so nothing breaks.
+- **New** UI copy and docs should follow **colour** in prose; new code symbols may still use `color` when matching surrounding APIs or conventions.

.cursor/rules/strict-user-scope.mdc

@@ -0,0 +1,16 @@
+---
+description: enforce strict user-scoped changes only
+alwaysApply: true
+---
+
+# Strict User Scope
+
+1. Only implement exactly what the user asked for in the current message.
+
+2. Do not add extra refactors, cleanups, renames, architecture changes, or behavioural changes unless the user explicitly asked for them.
+
+3. If a potential improvement is noticed, mention it briefly and ask before changing code.
+
+4. For revert/undo requests, perform the narrowest possible revert and do not modify anything else.
+
+5. Keep edits minimal and local to the requested area.

.cursor/rules/submodules-led-driver-tool.mdc

@@ -0,0 +1,18 @@
+---
+description: Keep led-driver and led-tool git submodules in sync when updating led-controller
+alwaysApply: true
+---
+
+# Submodule pointers (`led-driver`, `led-tool`)
+
+This repo tracks **`led-driver`** and **`led-tool`** as git submodules (see `.gitmodules`).
+
+When you **update led-controller** work that should ship with matching firmware or CLI behaviour—or when you finish changes **inside** those submodule directories—**record the new submodule commits in the parent repo**:
+
+1. In each submodule, commit and push on its remote if there are local commits (or ensure the checkout is the intended revision).
+2. From the **led-controller** root: `git add led-driver led-tool` after their HEADs point at the right commits.
+3. Include the parent-repo commit that bumps the gitlinks (so CI and clones get consistent trees).
+
+**Do not** leave submodule directories dirty or forgotten while presenting the parent repo as “done”: either commit the submodule pointer update in led-controller, or leave an explicit note if the user must push submodule remotes first.
+
+If the user only asked for a submodule bump with no code edits, a single `chore(submodules): bump led-driver and led-tool` style commit is appropriate (see commit rule).

.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+# led-driver/src is MicroPython source — never keep host __pycache__ there (see .cursor/rules/led-driver.mdc)
+led-driver/src/__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+scripts/.led-controller-venv
+docs/.help-print.html
+settings.json
+# Track shared JSON + preset binaries; ignore other db/*.json (e.g. device, zone) locally
+db/*
+!db/group.json
+!db/palette.json
+!db/pattern.json
+!db/preset.json
+!db/profile.json
+!db/scene.json
+!db/sequence.json
+!db/presets/
+!db/presets/*.bin
+*.log
+*.db
+*.sqlite
+.pytest_cache/
+.ropeproject/

.gitmodules

@@ -0,0 +1,9 @@
+[submodule "led-driver"]
+	path = led-driver
+	url = git@git.technical.kiwi:technicalkiwi/led-driver.git
+[submodule "led-tool"]
+	path = led-tool
+	url = git@git.technical.kiwi:technicalkiwi/led-tool.git
+[submodule "led-simulator"]
+	path = led-simulator
+	url = git@git.technical.kiwi:technicalkiwi/led-simulator.git

Pipfile

@@ -6,15 +6,29 @@ name = "pypi"
 [packages]
 mpremote = "*"
 pyserial = "*"
+pyserial-asyncio = "*"
 esptool = "*"
 pyjwt = "*"
 watchfiles = "*"
+requests = "*"
+selenium = "*"
+adafruit-ampy = "*"
+microdot = "*"
+websockets = "*"
+numpy = "*"
+sounddevice = "*"
 
 [dev-packages]
+pytest = "*"
 
 [requires]
-python_version = "3.12"
+python_version = "3.11"
 
 [scripts]
-web = "python /home/pi/led-controller/tests/web.py"
-watch = "python -m watchfiles 'python /home/pi/led-controller/tests/web.py' /home/pi/led-controller/src /home/pi/led-controller/tests"
+web = "python tests/web.py"
+watch = "python -m watchfiles \"python tests/web.py\" src tests"
+run = "sh -c 'cd src && python main.py'"
+dev = "python -m watchfiles \"sh -c 'cd src && LED_CONTROLLER_LIVE_RELOAD=1 python main.py'\" src"
+test = "python -m pytest"
+test-browser = "sh -c 'python tests/web.py > /tmp/led-controller-web.log 2>&1 & pid=$!; trap \"kill $pid\" EXIT; sleep 2; LED_CONTROLLER_RUN_BROWSER_TESTS=1 LED_CONTROLLER_DEVICE_IP=http://127.0.0.1:5000 python -m pytest tests/test_browser.py'"
+test-browser-device = "sh -c 'LED_CONTROLLER_RUN_BROWSER_TESTS=1 python -m pytest tests/test_browser.py'"

README.md

@@ -1,2 +1,45 @@
 # led-controller
 
+LED controller web app for managing profiles, **zones**, presets, and colour palettes, and sending commands to LED devices over **ESP-NOW** (binary wire format).
+
+- **Bridge ESP32**: runs a WebSocket server; the Pi connects as client (`bridge_ws_url` in `settings.json`, e.g. `ws://192.168.4.1/ws`).
+- **LED drivers**: announce on boot via ESP-NOW broadcast; the controller registers them and pushes group membership.
+- Architecture (diagrams): [docs/espnow-architecture.md](docs/espnow-architecture.md)
+- Wire format (byte layouts): [docs/espnow-binary-protocol.md](docs/espnow-binary-protocol.md) (≤250 bytes per frame, no JSON on the wire)
+
+## Run
+
+- One-time setup for port 80 without root: `sudo scripts/setup-port80.sh`
+- Start app: `pipenv run run` (override listen port with the **`PORT`** environment variable)
+- Dev watcher (auto-restart on `src/` changes): `pipenv run dev`
+- Regenerate **`docs/help.pdf`** from **`docs/help.md`**: `pipenv run help-pdf` (requires **pandoc** and **chromium** on the host)
+
+## UI modes
+
+- **Run mode**: focused control view. Select zones/presets and apply profiles. Editing actions are hidden.
+- **Edit mode**: management view. Shows **Zones**, Presets, Patterns, Colour Palette, and Send Presets controls, plus per-tile preset edit/remove and drag-reorder.
+
+## Profiles
+
+- Applying a profile updates session scope and refreshes the active zone content.
+- In **Run mode**, Profiles supports apply-only behaviour (no create/clone/delete).
+- In **Edit mode**, Profiles supports create/clone/delete.
+- Creating a profile always creates a populated `default` zone (starter presets).
+- Optional **DJ zone** seeding creates:
+  - `dj` zone bound to device name `dj`
+  - starter DJ presets (rainbow, single colour, transition)
+
+## Preset colours and palette linking
+
+- In preset editor, selecting a colour picker value auto-adds it when the picker closes.
+- Use **From Palette** to add a palette-linked preset colour.
+- Linked colours are stored as palette references and shown with a `P` badge.
+- When profile palette colours change, linked preset colours update across that profile.
+
+## API docs
+
+- Main API reference: `docs/API.md`
+
+## Driver pattern modules
+
+Pattern **`.py`** sources live under **`led-driver/src/patterns`**. The Pi app resolves that path via `util.driver_patterns.driver_patterns_dir()`. If you deploy without that tree next to the app, set **`LED_CONTROLLER_PATTERNS_DIR`** to the directory that contains those files.

bridge-serial/README.md

@@ -0,0 +1,19 @@
+# bridge-serial
+
+ESP32 ESP-NOW bridge with **USB/serial** uplink to the Pi (GPIO UART). Sync loop only — no asyncio, no Microdot.
+
+```
+bridge-serial/
+  src/
+    main.py       # entry
+    settings.py   # /settings.json on device
+```
+
+Deploy:
+
+```bash
+cd bridge-serial
+python ../led-tool/cli.py -p /dev/ttyUSB0 --src -r -f
+```
+
+No `--lib` required. Match `serial_baudrate` on the ESP and Pi (e.g. `921600`).

bridge-serial/src/main.py

@@ -0,0 +1,166 @@
+"""ESP-NOW bridge: Pi USB-serial downlink, ESP-NOW to drivers (sync loop)."""
+
+import gc, json, struct, time
+import espnow, machine, network
+from machine import Pin, UART
+from settings import Settings
+
+BROADCAST = b"\xff\xff\xff\xff\xff\xff"
+WIRE = 0x4C
+MAX_SERIAL = 4096
+MAX_ESPNOW = 250
+ESPNOW_EXIST = -12395
+ESPNOW_FULL = -12392
+
+
+def add_peer_if_needed(esp, dest, ch):
+    try:
+        esp.add_peer(dest, channel=ch)
+    except TypeError:
+        try:
+            esp.add_peer(dest)
+        except OSError as e:
+            if e.args[0] != ESPNOW_EXIST:
+                raise
+    except OSError as e:
+        if e.args[0] != ESPNOW_EXIST:
+            raise
+
+
+def del_peer_if_present(esp, dest):
+    try:
+        esp.del_peer(dest)
+    except Exception:
+        pass
+
+
+def send_unicast_temp_peer(esp, dest, ch, pkt):
+    try:
+        add_peer_if_needed(esp, dest, ch)
+    except OSError as e:
+        if e.args and e.args[0] == ESPNOW_FULL:
+            del_peer_if_present(esp, dest)
+            add_peer_if_needed(esp, dest, ch)
+        else:
+            raise
+    try:
+        esp.send(dest, pkt, True)
+    finally:
+        del_peer_if_present(esp, dest)
+
+
+def init_radio(ch, name, password):
+    network.WLAN(network.STA_IF).active(False)
+    network.WLAN(network.AP_IF).active(False)
+    time.sleep_ms(100)
+    ap = network.WLAN(network.AP_IF)
+    ap.active(True)
+    time.sleep_ms(50)
+    if password:
+        try:
+            ap.config(essid=name or "bridge", password=password, channel=ch, hidden=True)
+        except TypeError:
+            ap.config(essid=name or "bridge", channel=ch)
+    else:
+        try:
+            ap.config(essid=name or "bridge", channel=ch, hidden=True)
+        except TypeError:
+            ap.config(essid=name or "bridge", channel=ch)
+    sta = network.WLAN(network.STA_IF)
+    sta.active(True)
+    sta.config(pm=network.WLAN.PM_NONE)
+    try:
+        sta.config(channel=ch)
+    except Exception:
+        pass
+
+
+def mac_bytes(addr):
+    h = str(addr).replace(":", "").replace("-", "").strip().lower()
+    return bytes.fromhex(h)
+
+
+def read_serial(uart, buf):
+    if uart.any():
+        buf.extend(uart.read(min(uart.any(), 256)))
+    out = []
+    while len(buf) >= 2:
+        n = (buf[0] << 8) | buf[1]
+        if n > MAX_SERIAL:
+            buf[:] = buf[1:]
+            continue
+        need = 2 + n
+        if len(buf) < need:
+            break
+        out.append(bytes(buf[2:need]))
+        buf[:] = buf[need:]
+    return out
+
+
+def downlink(esp, ch, raw):
+    if not raw:
+        return
+    if raw[0] == WIRE:
+        if len(raw) < 2:
+            return
+        esp.send(BROADCAST, raw, True)
+        return
+    if len(raw) < 8 or raw[0] != ord("{"):
+        return
+    try:
+        data = json.loads(raw)
+    except ValueError:
+        return
+    devs = data.get("dv") or data.get("devices")
+    if data.get("v") != "1" or not isinstance(devs, dict):
+        return
+    for mac_s, body in devs.items():
+        if not isinstance(body, dict):
+            continue
+        try:
+            msg = {"v": "1"}
+            msg.update(body)
+            pkt = json.dumps(msg, separators=(",", ":")).encode()
+            if len(pkt) > MAX_ESPNOW:
+                continue
+            dest = mac_bytes(mac_s)
+        except (ValueError, TypeError):
+            continue
+        if dest == BROADCAST:
+            esp.send(BROADCAST, pkt, True)
+        else:
+            send_unicast_temp_peer(esp, dest, ch, pkt)
+        time.sleep_ms(5)
+
+
+gc.collect()
+s = Settings()
+ch = max(1, min(11, int(s.get("wifi_channel", 5))))
+init_radio(ch, s.get("name"), s.get("ap_password") or "")
+baud = int(s.get("serial_baudrate", 921600))
+uart = UART(
+    int(s.get("serial_uart_id", 1)),
+    baud,
+    tx=Pin(int(s.get("serial_tx_pin", 2))),
+    rx=Pin(int(s.get("serial_rx_pin", 3))),
+)
+esp = espnow.ESPNow()
+esp.active(True)
+add_peer_if_needed(esp, BROADCAST, ch)
+print("bridge ch", ch, "baud", baud, "heap", gc.mem_free())
+
+wdt = machine.WDT(timeout=10000)
+rx_buf = bytearray()
+while True:
+    wdt.feed()
+    for frame in read_serial(uart, rx_buf):
+        try:
+            downlink(esp, ch, frame)
+        except OSError as e:
+            print("dl", e)
+    host, msg = esp.recv(0)
+    if host:
+        up = bytes([0]) + host + msg
+        uart.write(struct.pack(">H", len(up)) + up)
+    else:
+        time.sleep_ms(1)

bridge-serial/src/settings.py

@@ -0,0 +1,62 @@
+import json
+import time
+import ubinascii
+import network
+
+WIFI_CHANNEL_DEFAULT = 5
+
+
+def _sta_mac_hex():
+    sta = network.WLAN(network.STA_IF)
+    was_on = sta.active()
+    if not was_on:
+        sta.active(True)
+        time.sleep_ms(50)
+    try:
+        mac = ubinascii.hexlify(sta.config("mac")).decode().lower()
+    except Exception:
+        mac = "000000000000"
+    if not was_on:
+        sta.active(False)
+    return mac
+
+
+class Settings(dict):
+    SETTINGS_FILE = "/settings.json"
+
+    def __init__(self):
+        super().__init__()
+        self.load()
+
+    def set_defaults(self):
+        self["name"] = "bridge-" + _sta_mac_hex()
+        self["wifi_channel"] = WIFI_CHANNEL_DEFAULT
+        self["ap_password"] = ""
+        self["serial_baudrate"] = 921600
+        self["serial_uart_id"] = 1
+        self["serial_tx_pin"] = 2
+        self["serial_rx_pin"] = 3
+        self["serial_usb"] = False
+
+    def save(self):
+        try:
+            with open(self.SETTINGS_FILE, "w") as f:
+                f.write(json.dumps(self))
+        except Exception as e:
+            print("save settings:", e)
+
+    def load(self):
+        try:
+            with open(self.SETTINGS_FILE, "r") as f:
+                loaded = json.load(f)
+            if not isinstance(loaded, dict):
+                raise ValueError("not object")
+        except Exception:
+            self.clear()
+            self.set_defaults()
+            self.save()
+            return
+        self.clear()
+        self.set_defaults()
+        for k, v in loaded.items():
+            self[k] = v

bridge-wifi/README.md

@@ -0,0 +1,22 @@
+# bridge-wifi
+
+ESP32 ESP-NOW bridge with **Wi‑Fi AP + WebSocket** (`/ws`). Same ESP-NOW downlink as bridge-serial.
+
+```
+bridge-wifi/
+  src/
+    main.py
+    settings.py
+    wifi_ap.py
+    espnow_wire.py   # uplink frame helper only
+  lib/microdot/      # WebSocket server
+```
+
+Deploy:
+
+```bash
+cd bridge-wifi
+python ../led-tool/cli.py -p /dev/ttyUSB0 --src --lib -r -f
+```
+
+Pi: join bridge AP, `bridge_ws_url` → `ws://192.168.4.1/ws`.

bridge-wifi/lib/microdot/__init__.py

@@ -0,0 +1,2 @@
+from microdot.microdot import Microdot, Request, Response, abort, redirect, \
+    send_file  # noqa: F401

bridge-wifi/lib/microdot/helpers.py

@@ -0,0 +1,8 @@
+try:
+    from functools import wraps
+except ImportError:  # pragma: no cover
+    # MicroPython does not currently implement functools.wraps
+    def wraps(wrapped):
+        def _(wrapper):
+            return wrapper
+        return _

bridge-wifi/lib/microdot/session.py

@@ -0,0 +1,225 @@
+try:
+    import jwt
+    HAS_JWT = True
+except ImportError:
+    HAS_JWT = False
+    try:
+        import ubinascii
+    except ImportError:
+        import binascii as ubinascii
+    try:
+        import uhashlib as hashlib
+    except ImportError:
+        import hashlib
+    try:
+        import uhmac as hmac
+    except ImportError:
+        try:
+            import hmac
+        except ImportError:
+            hmac = None
+    import json
+
+from microdot.microdot import invoke_handler
+from microdot.helpers import wraps
+
+
+class SessionDict(dict):
+    """A session dictionary.
+
+    The session dictionary is a standard Python dictionary that has been
+    extended with convenience ``save()`` and ``delete()`` methods.
+    """
+    def __init__(self, request, session_dict):
+        super().__init__(session_dict)
+        self.request = request
+
+    def save(self):
+        """Update the session cookie."""
+        self.request.app._session.update(self.request, self)
+
+    def delete(self):
+        """Delete the session cookie."""
+        self.request.app._session.delete(self.request)
+
+
+class Session:
+    """Session handling
+
+    :param app: The application instance.
+    :param secret_key: The secret key, as a string or bytes object.
+    :param cookie_options: A dictionary with cookie options to pass as
+                           arguments to :meth:`Response.set_cookie()
+                           <microdot.Response.set_cookie>`.
+    """
+    secret_key = None
+
+    def __init__(self, app=None, secret_key=None, cookie_options=None):
+        self.secret_key = secret_key
+        self.cookie_options = cookie_options or {}
+        if app is not None:
+            self.initialize(app)
+
+    def initialize(self, app, secret_key=None, cookie_options=None):
+        if secret_key is not None:
+            self.secret_key = secret_key
+        if cookie_options is not None:
+            self.cookie_options = cookie_options
+        if 'path' not in self.cookie_options:
+            self.cookie_options['path'] = '/'
+        if 'http_only' not in self.cookie_options:
+            self.cookie_options['http_only'] = True
+        app._session = self
+
+    def get(self, request):
+        """Retrieve the user session.
+
+        :param request: The client request.
+
+        The return value is a session dictionary with the data stored in the
+        user's session, or ``{}`` if the session data is not available or
+        invalid.
+        """
+        if not self.secret_key:
+            raise ValueError('The session secret key is not configured')
+        if hasattr(request.g, '_session'):
+            return request.g._session
+        session = request.cookies.get('session')
+        if session is None:
+            request.g._session = SessionDict(request, {})
+            return request.g._session
+        request.g._session = SessionDict(request, self.decode(session))
+        return request.g._session
+
+    def update(self, request, session):
+        """Update the user session.
+
+        :param request: The client request.
+        :param session: A dictionary with the update session data for the user.
+
+        Applications would normally not call this method directly, instead they
+        would use the :meth:`SessionDict.save` method on the session
+        dictionary, which calls this method. For example::
+
+            @app.route('/')
+            @with_session
+            def index(request, session):
+                session['foo'] = 'bar'
+                session.save()
+                return 'Hello, World!'
+
+        Calling this method adds a cookie with the updated session to the
+        request currently being processed.
+        """
+        if not self.secret_key:
+            raise ValueError('The session secret key is not configured')
+
+        encoded_session = self.encode(session)
+
+        @request.after_request
+        def _update_session(request, response):
+            response.set_cookie('session', encoded_session,
+                                **self.cookie_options)
+            return response
+
+    def delete(self, request):
+        """Remove the user session.
+
+        :param request: The client request.
+
+        Applications would normally not call this method directly, instead they
+        would use the :meth:`SessionDict.delete` method on the session
+        dictionary, which calls this method. For example::
+
+            @app.route('/')
+            @with_session
+            def index(request, session):
+                session.delete()
+                return 'Hello, World!'
+
+        Calling this method adds a cookie removal header to the request
+        currently being processed.
+        """
+        @request.after_request
+        def _delete_session(request, response):
+            response.delete_cookie('session', **self.cookie_options)
+            return response
+
+    def encode(self, payload, secret_key=None):
+        """Encode session data using JWT if available, otherwise use simple HMAC."""
+        if HAS_JWT:
+            return jwt.encode(payload, secret_key or self.secret_key,
+                              algorithm='HS256')
+        else:
+            # Simple encoding for MicroPython: base64(json) + HMAC signature
+            key = (secret_key or self.secret_key).encode() if isinstance(secret_key or self.secret_key, str) else (secret_key or self.secret_key)
+            payload_json = json.dumps(payload)
+            payload_b64 = ubinascii.b2a_base64(payload_json.encode()).decode().strip()
+            
+            # Create HMAC signature
+            if hmac:
+                # Use hmac module if available
+                h = hmac.new(key, payload_json.encode(), hashlib.sha256)
+            else:
+                # Fallback: simple SHA256(key + message)
+                h = hashlib.sha256(key + payload_json.encode())
+            signature = ubinascii.b2a_base64(h.digest()).decode().strip()
+            
+            return f"{payload_b64}.{signature}"
+
+    def decode(self, session, secret_key=None):
+        """Decode session data using JWT if available, otherwise use simple HMAC."""
+        if HAS_JWT:
+            try:
+                payload = jwt.decode(session, secret_key or self.secret_key,
+                                     algorithms=['HS256'])
+            except jwt.exceptions.PyJWTError:  # pragma: no cover
+                return {}
+            return payload
+        else:
+            try:
+                # Simple decoding for MicroPython
+                if '.' not in session:
+                    return {}
+                
+                payload_b64, signature = session.rsplit('.', 1)
+                payload_json = ubinascii.a2b_base64(payload_b64).decode()
+                
+                # Verify HMAC signature
+                key = (secret_key or self.secret_key).encode() if isinstance(secret_key or self.secret_key, str) else (secret_key or self.secret_key)
+                if hmac:
+                    # Use hmac module if available
+                    h = hmac.new(key, payload_json.encode(), hashlib.sha256)
+                else:
+                    # Fallback: simple SHA256(key + message)
+                    h = hashlib.sha256(key + payload_json.encode())
+                expected_signature = ubinascii.b2a_base64(h.digest()).decode().strip()
+                
+                if signature != expected_signature:
+                    return {}
+                
+                return json.loads(payload_json)
+            except Exception:
+                return {}
+
+
+def with_session(f):
+    """Decorator that passes the user session to the route handler.
+
+    The session dictionary is passed to the decorated function as an argument
+    after the request object. Example::
+
+        @app.route('/')
+        @with_session
+        def index(request, session):
+            return 'Hello, World!'
+
+    Note that the decorator does not save the session. To update the session,
+    call the :func:`session.save() <microdot.session.SessionDict.save>` method.
+    """
+    @wraps(f)
+    async def wrapper(request, *args, **kwargs):
+        return await invoke_handler(
+            f, request, request.app._session.get(request), *args, **kwargs)
+
+    return wrapper

bridge-wifi/lib/microdot/utemplate.py

@@ -0,0 +1,70 @@
+from utemplate import recompile
+
+_loader = None
+
+
+class Template:
+    """A template object.
+
+    :param template: The filename of the template to render, relative to the
+                     configured template directory.
+    """
+    @classmethod
+    def initialize(cls, template_dir='templates',
+                   loader_class=recompile.Loader):
+        """Initialize the templating subsystem.
+
+        :param template_dir: the directory where templates are stored. This
+                             argument is optional. The default is to load
+                             templates from a *templates* subdirectory.
+        :param loader_class: the ``utemplate.Loader`` class to use when loading
+                             templates. This argument is optional. The default
+                             is the ``recompile.Loader`` class, which
+                             automatically recompiles templates when they
+                             change.
+        """
+        global _loader
+        _loader = loader_class(None, template_dir)
+
+    def __init__(self, template):
+        if _loader is None:  # pragma: no cover
+            self.initialize()
+        #: The name of the template
+        self.name = template
+        self.template = _loader.load(template)
+
+    def generate(self, *args, **kwargs):
+        """Return a generator that renders the template in chunks, with the
+        given arguments."""
+        return self.template(*args, **kwargs)
+
+    def render(self, *args, **kwargs):
+        """Render the template with the given arguments and return it as a
+        string."""
+        return ''.join(self.generate(*args, **kwargs))
+
+    def generate_async(self, *args, **kwargs):
+        """Return an asynchronous generator that renders the template in
+        chunks, using the given arguments."""
+        class sync_to_async_iter():
+            def __init__(self, iter):
+                self.iter = iter
+
+            def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                try:
+                    return next(self.iter)
+                except StopIteration:
+                    raise StopAsyncIteration
+
+        return sync_to_async_iter(self.generate(*args, **kwargs))
+
+    async def render_async(self, *args, **kwargs):
+        """Render the template with the given arguments asynchronously and
+        return it as a string."""
+        response = ''
+        async for chunk in self.generate_async(*args, **kwargs):
+            response += chunk
+        return response

bridge-wifi/lib/microdot/websocket.py

@@ -0,0 +1,231 @@
+import binascii
+import hashlib
+from microdot import Request, Response
+from microdot.microdot import MUTED_SOCKET_ERRORS, print_exception
+from microdot.helpers import wraps
+
+
+class WebSocketError(Exception):
+    """Exception raised when an error occurs in a WebSocket connection."""
+    pass
+
+
+class WebSocket:
+    """A WebSocket connection object.
+
+    An instance of this class is sent to handler functions to manage the
+    WebSocket connection.
+    """
+    CONT = 0
+    TEXT = 1
+    BINARY = 2
+    CLOSE = 8
+    PING = 9
+    PONG = 10
+
+    #: Specify the maximum message size that can be received when calling the
+    #: ``receive()`` method. Messages with payloads that are larger than this
+    #: size will be rejected and the connection closed. Set to 0 to disable
+    #: the size check (be aware of potential security issues if you do this),
+    #: or to -1 to use the value set in
+    #: ``Request.max_body_length``. The default is -1.
+    #:
+    #: Example::
+    #:
+    #:    WebSocket.max_message_length = 4 * 1024  # up to 4KB messages
+    max_message_length = -1
+
+    def __init__(self, request):
+        self.request = request
+        self.closed = False
+
+    async def handshake(self):
+        response = self._handshake_response()
+        await self.request.sock[1].awrite(
+            b'HTTP/1.1 101 Switching Protocols\r\n')
+        await self.request.sock[1].awrite(b'Upgrade: websocket\r\n')
+        await self.request.sock[1].awrite(b'Connection: Upgrade\r\n')
+        await self.request.sock[1].awrite(
+            b'Sec-WebSocket-Accept: ' + response + b'\r\n\r\n')
+
+    async def receive(self):
+        """Receive a message from the client."""
+        while True:
+            opcode, payload = await self._read_frame()
+            send_opcode, data = self._process_websocket_frame(opcode, payload)
+            if send_opcode:  # pragma: no cover
+                await self.send(data, send_opcode)
+            elif data:  # pragma: no branch
+                return data
+
+    async def send(self, data, opcode=None):
+        """Send a message to the client.
+
+        :param data: the data to send, given as a string or bytes.
+        :param opcode: a custom frame opcode to use. If not given, the opcode
+                       is ``TEXT`` or ``BINARY`` depending on the type of the
+                       data.
+        """
+        frame = self._encode_websocket_frame(
+            opcode or (self.TEXT if isinstance(data, str) else self.BINARY),
+            data)
+        await self.request.sock[1].awrite(frame)
+
+    async def close(self):
+        """Close the websocket connection."""
+        if not self.closed:  # pragma: no cover
+            self.closed = True
+            await self.send(b'', self.CLOSE)
+
+    def _handshake_response(self):
+        connection = False
+        upgrade = False
+        websocket_key = None
+        for header, value in self.request.headers.items():
+            h = header.lower()
+            if h == 'connection':
+                connection = True
+                if 'upgrade' not in value.lower():
+                    return self.request.app.abort(400)
+            elif h == 'upgrade':
+                upgrade = True
+                if not value.lower() == 'websocket':
+                    return self.request.app.abort(400)
+            elif h == 'sec-websocket-key':
+                websocket_key = value
+        if not connection or not upgrade or not websocket_key:
+            return self.request.app.abort(400)
+        d = hashlib.sha1(websocket_key.encode())
+        d.update(b'258EAFA5-E914-47DA-95CA-C5AB0DC85B11')
+        return binascii.b2a_base64(d.digest())[:-1]
+
+    @classmethod
+    def _parse_frame_header(cls, header):
+        fin = header[0] & 0x80
+        opcode = header[0] & 0x0f
+        if fin == 0 or opcode == cls.CONT:  # pragma: no cover
+            raise WebSocketError('Continuation frames not supported')
+        has_mask = header[1] & 0x80
+        length = header[1] & 0x7f
+        if length == 126:
+            length = -2
+        elif length == 127:
+            length = -8
+        return fin, opcode, has_mask, length
+
+    def _process_websocket_frame(self, opcode, payload):
+        if opcode == self.TEXT:
+            payload = payload.decode()
+        elif opcode == self.BINARY:
+            pass
+        elif opcode == self.CLOSE:
+            raise WebSocketError('Websocket connection closed')
+        elif opcode == self.PING:
+            return self.PONG, payload
+        elif opcode == self.PONG:  # pragma: no branch
+            return None, None
+        return None, payload
+
+    @classmethod
+    def _encode_websocket_frame(cls, opcode, payload):
+        frame = bytearray()
+        frame.append(0x80 | opcode)
+        if opcode == cls.TEXT:
+            payload = payload.encode()
+        if len(payload) < 126:
+            frame.append(len(payload))
+        elif len(payload) < (1 << 16):
+            frame.append(126)
+            frame.extend(len(payload).to_bytes(2, 'big'))
+        else:
+            frame.append(127)
+            frame.extend(len(payload).to_bytes(8, 'big'))
+        frame.extend(payload)
+        return frame
+
+    async def _read_frame(self):
+        header = await self.request.sock[0].read(2)
+        if len(header) != 2:  # pragma: no cover
+            raise WebSocketError('Websocket connection closed')
+        fin, opcode, has_mask, length = self._parse_frame_header(header)
+        if length == -2:
+            length = await self.request.sock[0].read(2)
+            length = int.from_bytes(length, 'big')
+        elif length == -8:
+            length = await self.request.sock[0].read(8)
+            length = int.from_bytes(length, 'big')
+        max_allowed_length = Request.max_body_length \
+            if self.max_message_length == -1 else self.max_message_length
+        if length > max_allowed_length:
+            raise WebSocketError('Message too large')
+        if has_mask:  # pragma: no cover
+            mask = await self.request.sock[0].read(4)
+        payload = await self.request.sock[0].read(length)
+        if has_mask:  # pragma: no cover
+            payload = bytes(x ^ mask[i % 4] for i, x in enumerate(payload))
+        return opcode, payload
+
+
+async def websocket_upgrade(request):
+    """Upgrade a request handler to a websocket connection.
+
+    This function can be called directly inside a route function to process a
+    WebSocket upgrade handshake, for example after the user's credentials are
+    verified. The function returns the websocket object::
+
+        @app.route('/echo')
+        async def echo(request):
+            if not authenticate_user(request):
+                abort(401)
+            ws = await websocket_upgrade(request)
+            while True:
+                message = await ws.receive()
+                await ws.send(message)
+    """
+    ws = WebSocket(request)
+    await ws.handshake()
+
+    @request.after_request
+    async def after_request(request, response):
+        return Response.already_handled
+
+    return ws
+
+
+def websocket_wrapper(f, upgrade_function):
+    @wraps(f)
+    async def wrapper(request, *args, **kwargs):
+        ws = await upgrade_function(request)
+        try:
+            await f(request, ws, *args, **kwargs)
+        except OSError as exc:
+            if exc.errno not in MUTED_SOCKET_ERRORS:  # pragma: no cover
+                raise
+        except WebSocketError:
+            pass
+        except Exception as exc:
+            print_exception(exc)
+        finally:  # pragma: no cover
+            try:
+                await ws.close()
+            except Exception:
+                pass
+        return Response.already_handled
+    return wrapper
+
+
+def with_websocket(f):
+    """Decorator to make a route a WebSocket endpoint.
+
+    This decorator is used to define a route that accepts websocket
+    connections. The route then receives a websocket object as a second
+    argument that it can use to send and receive messages::
+
+        @app.route('/echo')
+        @with_websocket
+        async def echo(request, ws):
+            while True:
+                message = await ws.receive()
+                await ws.send(message)
+    """
+    return websocket_wrapper(f, websocket_upgrade)

bridge-wifi/src/espnow_wire.py

@@ -0,0 +1,7 @@
+"""WebSocket uplink framing (Pi ↔ bridge)."""
+
+BROADCAST_MAC = b"\xff\xff\xff\xff\xff\xff"
+
+
+def pack_ws_uplink(peer, espnow_packet):
+    return bytes([0]) + peer + espnow_packet

bridge-wifi/src/main.py

@@ -0,0 +1,218 @@
+"""ESP-NOW bridge: Pi WebSocket downlink, ESP-NOW to drivers."""
+
+import asyncio
+import gc
+import json
+import time
+
+import espnow
+import machine
+from espnow_wire import BROADCAST_MAC, pack_ws_uplink
+from microdot import Microdot
+from microdot.websocket import WebSocketError, with_websocket
+from settings import Settings
+from wifi_ap import init_bridge_network
+
+BROADCAST = BROADCAST_MAC
+WIRE = 0x4C
+MAX_ESPNOW = 250
+ESPNOW_EXIST = -12395
+ESPNOW_FULL = -12392
+
+
+def mac_str(mac):
+    return ":".join("%02x" % b for b in mac)
+
+
+def dbg(msg):
+    if DEBUG:
+        print(msg)
+
+
+def add_peer_if_needed(esp, dest, ch):
+    try:
+        esp.add_peer(dest, channel=ch)
+        dbg("peer add " + mac_str(dest))
+    except TypeError:
+        try:
+            esp.add_peer(dest)
+            dbg("peer add " + mac_str(dest))
+        except OSError as e:
+            if e.args[0] != ESPNOW_EXIST:
+                raise
+            dbg("peer exists " + mac_str(dest))
+    except OSError as e:
+        if e.args[0] != ESPNOW_EXIST:
+            raise
+        dbg("peer exists " + mac_str(dest))
+
+
+def del_peer_if_present(esp, dest):
+    try:
+        esp.del_peer(dest)
+        dbg("peer del " + mac_str(dest))
+    except Exception as e:
+        dbg("peer del skip " + mac_str(dest) + " " + repr(e))
+
+
+def send_espnow(esp, dest, pkt):
+    try:
+        esp.send(dest, pkt, True)
+        return True
+    except OSError as e:
+        label = "bcast" if dest == BROADCAST else mac_str(dest)
+        print("send err", label, len(pkt), e)
+        return False
+
+
+def send_unicast_temp_peer(esp, dest, ch, pkt):
+    try:
+        add_peer_if_needed(esp, dest, ch)
+    except OSError as e:
+        # If peer table is full but this peer already exists, delete+retry once.
+        if e.args and e.args[0] == ESPNOW_FULL:
+            dbg("peer full " + mac_str(dest) + " retry")
+            del_peer_if_present(esp, dest)
+            add_peer_if_needed(esp, dest, ch)
+        else:
+            raise
+    ok = send_espnow(esp, dest, pkt)
+    del_peer_if_present(esp, dest)
+    return ok
+
+
+def downlink(esp, ch, raw):
+    n = len(raw)
+    if not raw:
+        return
+    if raw[0] == WIRE:
+        if n < 2:
+            dbg("dl skip wire short " + str(n))
+            return
+        dbg("dl wire bcast " + str(n))
+        send_espnow(esp, BROADCAST, raw)
+        return
+    if n < 8 or raw[0] != ord("{"):
+        dbg("dl skip json " + str(n))
+        return
+    try:
+        data = json.loads(raw)
+    except ValueError:
+        dbg("dl skip json")
+        return
+    devs = data.get("dv") or data.get("devices")
+    if data.get("v") != "1" or not isinstance(devs, dict):
+        dbg("dl skip envelope")
+        return
+    dbg("dl env " + str(len(devs)) + " dev")
+    for mac_s, body in devs.items():
+        if not isinstance(body, dict):
+            dbg("dl skip body " + str(mac_s))
+            continue
+        try:
+            h = str(mac_s).replace(":", "").replace("-", "").strip().lower()
+            dest = BROADCAST if h == "ffffffffffff" else bytes.fromhex(h)
+            msg = {"v": "1"}
+            msg.update(body)
+            pkt = json.dumps(msg, separators=(",", ":")).encode()
+            if len(pkt) > MAX_ESPNOW:
+                dbg("dl skip big " + str(len(pkt)))
+                continue
+        except (ValueError, TypeError):
+            dbg("dl skip mac " + str(mac_s))
+            continue
+        if dest == BROADCAST:
+            dbg("dl bcast " + str(len(pkt)))
+            send_espnow(esp, BROADCAST, pkt)
+        else:
+            dbg("dl uni " + mac_str(dest) + " " + str(len(pkt)))
+            send_unicast_temp_peer(esp, dest, ch, pkt)
+        time.sleep_ms(5)
+
+
+gc.collect()
+settings = Settings()
+DEBUG = bool(settings.get("debug", True))
+ch = max(1, min(11, int(settings.get("wifi_channel", 5))))
+init_bridge_network(settings)
+
+esp = espnow.ESPNow()
+esp.active(True)
+add_peer_if_needed(esp, BROADCAST, ch)
+print(
+    "bridge-wifi ch",
+    ch,
+    "debug",
+    DEBUG,
+    "heap",
+    gc.mem_free(),
+    "ws",
+    int(settings.get("ws_port", 80)),
+)
+
+app = Microdot()
+clients = set()
+wdt = machine.WDT(timeout=10000)
+
+
+@app.route("/ws")
+@with_websocket
+async def ws_handler(request, ws):
+    clients.add(ws)
+    print("ws client +", len(clients))
+    try:
+        while True:
+            try:
+                raw = await ws.receive()
+            except WebSocketError:
+                dbg("ws closed")
+                break
+            if not raw:
+                dbg("ws empty")
+                break
+            if isinstance(raw, str):
+                raw = raw.encode("utf-8")
+            dbg("ws rx " + str(len(raw)))
+            try:
+                downlink(esp, ch, raw)
+            except OSError as e:
+                print("dl err", e)
+    finally:
+        clients.discard(ws)
+        print("ws client -", len(clients))
+
+
+async def espnow_rx_loop():
+    while True:
+        host, msg = esp.recv(0)
+        if host:
+            dbg("up " + mac_str(host) + " " + str(len(msg)))
+            frame = pack_ws_uplink(host, msg)
+            dead = []
+            sent = 0
+            for ws in list(clients):
+                try:
+                    await ws.send(frame)
+                    sent += 1
+                except Exception as e:
+                    dbg("ws up err " + repr(e))
+                    dead.append(ws)
+            for ws in dead:
+                clients.discard(ws)
+            if not clients:
+                dbg("up no ws clients")
+            else:
+                dbg("up ws " + str(sent) + "/" + str(len(clients)))
+        else:
+            await asyncio.sleep_ms(1)
+        wdt.feed()
+
+
+async def main():
+    asyncio.create_task(espnow_rx_loop())
+    port = int(settings.get("ws_port", 80))
+    print("ws listen", port)
+    await app.start_server(host="0.0.0.0", port=port)
+
+
+asyncio.run(main())

bridge-wifi/src/settings.py

@@ -0,0 +1,60 @@
+import json
+import time
+import ubinascii
+import network
+
+WIFI_CHANNEL_DEFAULT = 5
+
+
+def _sta_mac_hex():
+    sta = network.WLAN(network.STA_IF)
+    was_on = sta.active()
+    if not was_on:
+        sta.active(True)
+        time.sleep_ms(50)
+    try:
+        mac = ubinascii.hexlify(sta.config("mac")).decode().lower()
+    except Exception:
+        mac = "000000000000"
+    if not was_on:
+        sta.active(False)
+    return mac
+
+
+class Settings(dict):
+    SETTINGS_FILE = "/settings.json"
+
+    def __init__(self):
+        super().__init__()
+        self.load()
+
+    def set_defaults(self):
+        self["name"] = "bridge-" + _sta_mac_hex()
+        self["wifi_channel"] = WIFI_CHANNEL_DEFAULT
+        self["ap_password"] = ""
+        self["ap_ip"] = "192.168.4.1"
+        self["ws_port"] = 80
+        self["debug"] = True
+
+    def save(self):
+        try:
+            with open(self.SETTINGS_FILE, "w") as f:
+                f.write(json.dumps(self))
+        except Exception as e:
+            print("save settings:", e)
+
+    def load(self):
+        try:
+            with open(self.SETTINGS_FILE, "r") as f:
+                loaded = json.load(f)
+            if not isinstance(loaded, dict):
+                raise ValueError("not object")
+        except Exception:
+            self.clear()
+            self.set_defaults()
+            self.save()
+            return
+        self.clear()
+        self.set_defaults()
+        for k, v in loaded.items():
+            self[k] = v

bridge-wifi/src/wifi_ap.py

@@ -0,0 +1,52 @@
+"""AP + STA for ESP-NOW; Pi joins the AP for WebSocket."""
+
+import time
+
+import network
+
+from settings import WIFI_CHANNEL_DEFAULT
+
+
+def _channel(settings):
+    try:
+        return max(1, min(11, int(settings.get("wifi_channel", WIFI_CHANNEL_DEFAULT))))
+    except (TypeError, ValueError):
+        return WIFI_CHANNEL_DEFAULT
+
+
+def init_bridge_network(settings):
+    ch = _channel(settings)
+    essid = settings.get("name") or "bridge"
+    password = settings.get("ap_password") or ""
+    ap_ip = settings.get("ap_ip") or "192.168.4.1"
+
+    sta = network.WLAN(network.STA_IF)
+    ap = network.WLAN(network.AP_IF)
+    sta.active(False)
+    ap.active(False)
+    time.sleep_ms(100)
+
+    ap.active(True)
+    time.sleep_ms(50)
+    if password:
+        try:
+            ap.config(essid=essid, password=password, channel=ch)
+        except TypeError:
+            ap.config(essid=essid, channel=ch)
+    else:
+        ap.config(essid=essid, channel=ch)
+    try:
+        ap.ifconfig((ap_ip, "255.255.255.0", ap_ip, "8.8.8.8"))
+    except Exception:
+        pass
+
+    sta.active(True)
+    sta.config(pm=network.WLAN.PM_NONE)
+    try:
+        sta.config(channel=ch)
+    except Exception:
+        pass
+
+    port = int(settings.get("ws_port", 80))
+    print("bridge AP", essid, "ch", ch, "ip", ap.ifconfig()[0])
+    print("bridge_ws_url: ws://%s:%s/ws" % (ap_ip, port))

clear-debug-log.sh

@@ -1,2 +0,0 @@
-#!/usr/bin/env sh
-rm -f /home/pi/led-controller/.cursor/debug.log

db/palette.json

@@ -1,39 +1 @@
-{
-    "1": {
-        "name": "Default Colors",
-        "colors": [
-            "#FF0000",
-            "#00FF00",
-            "#0000FF",
-            "#FFFF00",
-            "#FF00FF",
-            "#00FFFF",
-            "#FFFFFF",
-            "#000000",
-            "#FFA500",
-            "#800080"
-        ]
-    },
-    "2": {
-        "name": "Warm Colors",
-        "colors": [
-            "#FF6B6B",
-            "#FF8E53",
-            "#FFA07A",
-            "#FFD700",
-            "#FFA500",
-            "#FF6347"
-        ]
-    },
-    "3": {
-        "name": "Cool Colors",
-        "colors": [
-            "#4ECDC4",
-            "#44A08D",
-            "#96CEB4",
-            "#A8E6CF",
-            "#5F9EA0",
-            "#4682B4"
-        ]
-    }
-}
+{"1":["#FF0000","#00FF00","#0000FF","#FFFF00","#FF00FF","#00FFFF","#FFFFFF","#000000","#050500"],"2":[],"3":[],"4":[],"5":[],"6":[],"7":["#FF0000","#00FF00","#0000FF","#FFFF00","#FF00FF","#00FFFF","#FFFFFF","#000000"],"8":[],"9":[],"10":[],"11":[],"12":["#890b0b","#0b8935"],"13":[],"14":["#E8F4FF","#9ECFFF","#5080C8","#FFFFFF","#B0DCFF","#0A1520","#FF8020","#071018"]}

db/pattern.json

@@ -1,54 +1,280 @@
 {
-    "on": {
-            "min_delay": 10,
-            "max_delay": 10000,
-            "max_colors": 1
-        },
-    "off": {
-        "min_delay": 10,
-        "max_delay": 10000,
-        "max_colors": 0
+  "on": {
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 1,
+    "supports_manual": true
+  },
+  "off": {
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 0,
+    "supports_manual": true
+  },
+  "colour_cycle": {
+    "supports_reverse": true,
+    "n1": "Step rate",
+    "mode": {
+      "0": "Scroll palette gradient",
+      "1": "Rainbow wheel (preset colours ignored)"
     },
-    "rainbow": {
-        "n1": "Step Rate",
-        "min_delay": 10,
-        "max_delay": 10000,
-        "max_colors": 0
-    },
-    "transition": {
-        "min_delay": 10,
-        "max_delay": 10000,
-        "max_colors": 10
-    },
-    "chase": {
-        "n1": "Colour 1 Length",
-        "n2": "Colour 2 Length",
-        "n3": "Step 1",
-        "n4": "Step 2",
-        "min_delay": 10,
-        "max_delay": 10000,
-        "max_colors": 2
-    },
-    "pulse": {
-        "n1": "Attack",
-        "n2": "Hold",
-        "n3": "Decay",
-        "min_delay": 10,
-        "max_delay": 10000,
-        "max_colors": 10
-    },
-    "circle": {
-        "n1": "Head Rate",
-        "n2": "Max Length",
-        "n3": "Tail Rate",
-        "n4": "Min Length",
-        "min_delay": 10,
-        "max_delay": 10000,
-        "max_colors": 2
-    },
-    "blink": {
-        "min_delay": 10,
-        "max_delay": 10000,
-        "max_colors": 10
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 10,
+    "supports_manual": true
+  },
+  "transition": {
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 10,
+    "supports_manual": false
+  },
+  "chase": {
+    "supports_reverse": true,
+    "n1": "Colour 1 Length",
+    "n2": "Colour 2 Length",
+    "n3": "Step 1",
+    "n4": "Step 2",
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 2,
+    "has_background": true,
+    "supports_manual": true,
+    "mode": {
+      "0": "Two-colour chase",
+      "1": "Marquee dashes (n1 on length, n2 off, n3 step)"
     }
-}
+  },
+  "pulse": {
+    "n1": "Attack",
+    "n2": "Hold",
+    "n3": "Decay",
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 10,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "circle": {
+    "n1": "Head Rate",
+    "n2": "Max Length",
+    "n3": "Tail Rate",
+    "n4": "Min Length",
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 2,
+    "has_background": true,
+    "supports_manual": false
+  },
+  "blink": {
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 10,
+    "has_background": true,
+    "supports_manual": false
+  },
+  "flicker": {
+    "n1": "Min brightness",
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 10,
+    "supports_manual": true
+  },
+  "flame": {
+    "n1": "Min brightness",
+    "n2": "Breath period (ms)",
+    "n3": "Spark gap min (ms, 0=default 10\u201330 s, -1=off)",
+    "n4": "Spark gap max (ms)",
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 10,
+    "supports_manual": false
+  },
+  "twinkle": {
+    "n1": "Twinkle activity (1\u2013255, higher = more changes)",
+    "n2": "Density (0\u2013255, higher = more of the strip lit)",
+    "n3": "Min adjacent LEDs per twinkle (same as max for fixed length)",
+    "n4": "Max adjacent LEDs per twinkle (same as min for fixed length)",
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 10,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "radiate": {
+    "n1": "Node spacing (LEDs)",
+    "n2": "Out time (ms)",
+    "n3": "In time (ms)",
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 10,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "plasma": {
+    "n1": "Scale",
+    "n2": "Speed",
+    "n3": "Contrast",
+    "max_colors": 10,
+    "min_delay": 10,
+    "max_delay": 10000,
+    "supports_manual": false
+  },
+  "bar_graph": {
+    "n1": "Level percent",
+    "max_colors": 10,
+    "min_delay": 10,
+    "max_delay": 10000,
+    "has_background": true,
+    "supports_manual": false
+  },
+  "strobe_burst": {
+    "n1": "Burst count",
+    "n2": "Burst gap",
+    "n3": "Cooldown",
+    "max_colors": 10,
+    "min_delay": 10,
+    "max_delay": 10000,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "rain_drops": {
+    "n1": "Drop rate",
+    "n2": "Ripple width",
+    "max_colors": 10,
+    "min_delay": 10,
+    "max_delay": 10000,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "clock_sweep": {
+    "n1": "Hand width",
+    "n2": "Marker interval",
+    "max_colors": 10,
+    "min_delay": 10,
+    "max_delay": 10000,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "aurora": {
+    "supports_reverse": true,
+    "n1": "Band count (0) or spatial period LEDs (1)",
+    "n2": "Shimmer (0) or blend strength (1)",
+    "n3": "Unused (0) or drift speed (1)",
+    "mode": {
+      "0": "Colour bands + shimmer",
+      "1": "Sine northern wave"
+    },
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 10,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "icicles": {
+    "supports_reverse": true,
+    "n1": "Anchor spacing (LEDs)",
+    "n2": "Max icicle length (LEDs)",
+    "n3": "Phase step per refresh",
+    "max_colors": 10,
+    "min_delay": 10,
+    "max_delay": 10000,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "blizzard": {
+    "supports_reverse": true,
+    "n1": "Flake density",
+    "n2": "Fall speed",
+    "n3": "Wind (128 = centred; lower/raise for drift bias)",
+    "max_colors": 10,
+    "min_delay": 10,
+    "max_delay": 10000,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "rime": {
+    "n1": "Crystallisation rate",
+    "n2": "Melt (decay) per refresh",
+    "n3": "Spark cap (LEDs refreshed per cycle)",
+    "max_colors": 10,
+    "min_delay": 10,
+    "max_delay": 10000,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "candle_glow": {
+    "n1": "Candle count",
+    "n2": "Glow width (LEDs)",
+    "n3": "Flicker strength",
+    "max_colors": 10,
+    "min_delay": 10,
+    "max_delay": 10000,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "orbit": {
+    "n1": "Orbit count",
+    "n2": "Base speed",
+    "max_colors": 10,
+    "min_delay": 10,
+    "max_delay": 10000,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "palette_morph": {
+    "n1": "Morph ms",
+    "n2": "Warp rate",
+    "n3": "Turbulence",
+    "max_colors": 10,
+    "min_delay": 10,
+    "max_delay": 10000,
+    "supports_manual": false
+  },
+  "meteor": {
+    "supports_reverse": true,
+    "n1": "Tail length (0–1) or eye width (2)",
+    "n2": "Speed (LEDs per frame)",
+    "n3": "Fade amount (0), comet gap (1), or end pause frames (2)",
+    "mode": {
+      "0": "Fading meteor",
+      "1": "Dual comets",
+      "2": "Bouncing scanner"
+    },
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 10,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "particles": {
+    "supports_reverse": true,
+    "n1": "Flake density (0) or spawn rate (1)",
+    "n2": "Fall speed (LEDs per frame)",
+    "n3": "Unused (0) or streak length (1)",
+    "mode": {
+      "0": "Snowfall flakes",
+      "1": "Starfall streaks"
+    },
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 10,
+    "has_background": true,
+    "supports_manual": true
+  },
+  "sparkle": {
+    "n1": "Spark density (0–1) or firefly count (2)",
+    "n2": "Trail decay (0) or twinkle speed (2)",
+    "n3": "Ice halo width LEDs (1); unused in 0 and 2",
+    "mode": {
+      "0": "Sparkle trail",
+      "1": "Ice burst + halo",
+      "2": "Fireflies"
+    },
+    "min_delay": 10,
+    "max_delay": 10000,
+    "max_colors": 10,
+    "has_background": true,
+    "supports_manual": true
+  }
+}

db/presets/10.bin

@@ -0,0 +1,3 @@
+PRST1xœ%ÎÁ
+Â0Ð_‘ñšCSµJîæ'D$¶«
+ÄÝ’¦ˆˆÿntOovæ²opxz‘´zŽ±¦P

db/presets/11.bin

@@ -0,0 +1,2 @@
+PRST1xњ%ОAВ …б»<·,J5\Е4
+К $84SX4Ж»‹eхеНlюШЅ	B

db/presets/12.bin

@@ -0,0 +1 @@
+PRST1xœ%ÎA л|·, ŠÐK˜ÆP;*	

db/presets/13.bin

@@ -0,0 +1,2 @@
+PRST1xœEÎÁ
+Â0Ð_‘9ç`«Qɯˆ”Ô®ˆ»e“RDüwsðô˜™Ë¼ÁñIИx”uS²¬p˜c­¤ü¬»J-ç‹Ã¨éþ¨LÅrï½ÃD9¾:¿uˆK„ª9pg¥Ñ#Ø»ƾá‡Æ±qú1«ÜR¦!Mö¡Ãç<0B><>1

db/presets/14.bin

@@ -0,0 +1,2 @@
+PRST1xœ=ÎÝ
+!†á[‰¯StK[¼€½‰ˆ°v*ÁTü!"º÷ܤŽžá<C5BE>9˜¼¹4bu™VÙ…¢)…’ÿåVÎÁ…”¡÷XO“RœãÀpJöz+žr[R2ÌäÌzäœÁÔ KªÄàE;àKõ´èÓæ߶в£:»Îø%¦p±ŽŽvn?	¼?<3F>¨2ú

db/presets/3.bin

@@ -0,0 +1,2 @@
+PRST1xœUÎÁ
+Â0ЙsM5Uò+"²µ«â¦lSDÄwiNž³3‡ý@èɈPJ2–fª•Uþn×’‹.ˆ§³Ã¨éþ¨Â‹å>‡‰3½}×9ÐZbÕ•ÄÛÀè­‘]cß<08>¡qh7f-·”ù’&ûÁãûF9/.

db/presets/30.bin

@@ -0,0 +1,2 @@
+PRST1xœEÎÁ
+Â0Ð_‘9ç`«Qɯˆ”Ô®ˆ»e“RDüwsðô˜™Ë¼ÁñIИx”uS²¬p˜c­¤ü¬»J-ç‹Ã¨éþ¨LÅrï½ÃD9¾:¿uˆK„ª9pg¥Ñ#Ø»ƾá‡Æ±qú1«ÜR¦!Mö¡Çç<0B>“1

db/presets/32.bin

@@ -0,0 +1,2 @@
+PRST1xœ%ͽÂ0àW©Ž5C~•&VÆ
+¡@<40>)uª4K…xwR<}ç»Á°	—ks<DjÎ)¦…É•B™ë–¸ž¯µža;l¼×Ú{Üž9ïÂ4×Á­ÐStl«kævÅ[a'ì…ƒpN¦œ|ˆô}ýmðý
‡-‰

db/presets/33.bin

@@ -0,0 +1 @@
+PRST1xœMÎ1!†á¿b¾[=5ÌNÎnÆô@I°\€Åÿ»Å.²<oÚ¼Aîéa±?,ŽÅQ<C385>-f‚ÂìZó…xÓþÇ·œr©°'!h~<´î-Õg…k‰÷G#_ùØ­0ùä^Ü#7-a;FX	ka6ÂVØý˜K1ùKœø_Ÿ/ÐM4y

db/presets/35.bin

@@ -0,0 +1,2 @@
+PRST1xœ%ͽÂ0àW©Ž5C~•&VÆ
+¡@<40>)uª4K…xwR<}ç»Á°	—ks<DjÎ)¦…É•B™ë–¸ž¯µža;l¼×Ú{Üž9ïÂ4×Á­ÐStl«kævÅ[a'ì…ƒpN¦œ|ˆô}ýmðý
‡-‰

db/presets/36.bin

@@ -0,0 +1 @@
+PRST1xœMÎ1!†á¿b¾[=5ÌNÎnÆô@I°\€Åÿ»Å.²<oÚ¼Aîéa±?,ŽÅQ<C385>-f‚ÂìZó…xÓþÇ·œr©°'!h~<´î-Õg…k‰÷G#_ùØ­0ùä^Ü#7-a;FX	ka6ÂVØý˜K1ùKœø_Ÿ/ÐM4y

db/presets/39.bin

@@ -0,0 +1,3 @@
+PRST1xœUÎÁ‚0„áw¯=¤jú*†<>
+[m\[²”ƒ1¾»…ž<}ÉÌåÿ ºÁÂsŸ$P˜]Î$ño'Y`¯88ÒÚ{ô
+7	÷GŽ´”£5Fa"voX£Üšl–•bÛè2ÆvãXé*¦rªœ+—<>Y’LC˜JM³·1•ºAÈo5qeî¿?ªð9±

db/presets/40.bin

@@ -0,0 +1,4 @@
+PRST1xśMÎÁ‚0„áwŻ=$ű*†<>
+[%Y[RÚ1ľ»…^<}ÉĚĺ˙Ŕ™7<E284A2>`ĺPa51rpËäŇ
+tÇĹÚ©×<1A>Â#,ĎWtĽĺŁŞ{…™Ĺě V+<2B>=(†Ä
+®5m¶՝ίk@×B[č

db/presets/41.bin

@@ -0,0 +1,2 @@
+PRST1xśmŹÁ‚0†ßĄ\wČ`ŮMQ^Â2ĄčâÜČ1ĆřînĚ‹‰—~í—?Mű#ďüC™›F 0IďŃ™w¶ÚşÄ˛š7Ľm<C4BD>ËĺMęveýuUąo<v[şć:'§.Wop
+Ć¨ĺDN)
ąx»	<09><H¤)B2r"˘Śá@–Ć*ˇNŕ+&gGĄ±WC8<_ßĐéŽńpłhMţ”îý
Ź!I°

db/presets/42.bin

@@ -0,0 +1,2 @@
+PRST1xњUЋ;В0птТєp>°WAQґђ5X2Nд8BЬ;©hv¤·SМЃ_BдЙq(,њ’Др·Эg?ЗtEЕЅЦЦж­ТZіf
+·иПdНJcЊВ$ћЯ “ЮТJq…PѓЪј…t)ПР‚є]ЁАињњw,q¶ОЛи¦\Wп­^rнЕ–є°yЇКѕ?Эh>Ў

db/presets/44.bin

@@ -0,0 +1,2 @@
+PRST1xœEÎM
+Â0à«Ès›Eÿ¢’ôE$¶£â¤$Ó…ˆww0góÁ{o1o°„ŠìÊì™)Ã`õ"”Y‹6§˜r<CB9C>›°ÇFgƒk÷‡0-:k

db/presets/45.bin

@@ -0,0 +1,3 @@
+PRST1xœ=ŽA‚0E¯B>Û.
+*š€KC*ŒØ¤¶¤Æxw<1B>Í{™7‹y!ØÁ€)s5';9
+\å1Eï¡°XfJA~mø·1ú˜2ÌußkÙÕZo^ls\®ÉÍw”å¸mµÂDÞ>a:Q»r„á´’Bh¤Z)aW°/8tÇ‚ÓKŠ7çip“üÙàý
)<¡

db/presets/46.bin

@@ -0,0 +1,3 @@
+PRST1xś-ÎÁ‚0Đ_!õ‡Šdo˝ô'Ś!Ş’”–”ĺ`Ś˙î<˝ÍĚö<>čfű•‹!Íž‹qs

+‹cö9J·Çý?RHy]QZkŚÖ’•Zc-n
+÷<=_ý*“Zk…Ń÷µrşŤ<13>óćbę„T	

db/presets/47.bin

@@ -0,0 +1,2 @@
+PRST1x<EFBFBD>5־A‚0…ב«<D791>ַ¶@Dׂ-	—0ֶT©<54>X[2ֶxwG׳ש&‎»˜‚yXh°M\₪<>׀<EFBFBD><D780>‚ֹ8…<>0[
+’ור/חט#%ט=ֺ¾†q”·r\…¹כ<C2B9>ƒMע¥©*…ֹzף„מd5Gh¦ֵ*„Zz+6b-1l ¿´™m¦ֻל2‎ֺLסגה"7ֹy5<79>־ד:G

db/presets/48.bin

@@ -0,0 +1,2 @@
+PRST1xœ-ÎÁ Ð_1ã•ÔZŽúÆ´«’ 4°Õã¿»Š§7;sÙ¢»,˜
+/îNP˜3å(í¿8¥<38>r<EFBFBD>Ýa©õ¶ìŽÙ_®©ÈÐh­0RpOØN¢›9ÁržI!XÓˆ<C393>ØËW„ö{­+]eSéL9<4C>} ƒåƒ÷ªù0¿

db/presets/49.bin

@@ -0,0 +1,2 @@
+PRST1x<EFBFBD>=ЮA
+Т0аЋШw<D0A8>EZ5JаK<14>б<EFBFBD>ZH<5A><48>L"онС<D0BD>Ћ7ќџѓFЄ<46>с!\e<>е<>`<60>I<EFBFBD>KдќнRHЅТ<D085>и<0E>ЕЮсlp-ѓу)<29>ЋНЕzС;=i<>/ee<65>иiІє:Sv<53>=МютЁсЧЦщG.щ>ОЬ<D09E>Овсѓ,<2C>1И

db/presets/50.bin

@@ -0,0 +1,2 @@
+PRST1xœ5ÎA‚0Ы<C390>϶‹‚ˆ¦è%Œ!F <20>–´ÃÂïîhu6o2ÿ/æ	ïV‚
Sâ"Ѹ’碟\"(lŽ™¢—ø—tÿ¤Kˆ	æ‚ÒZ-#·ò£µ¸*Üâ<Nì)I¥ÖZa Å=`ZYÝÎ
†ãN
+¾‚i„¦0RðMæ˜i3§ÌùËÃ}^¨›ù­Âë

db/presets/53.bin

@@ -0,0 +1,2 @@
+PRST1xœ5Î=Â0†á«Tk†þQ<C3BE>À%*T%Ô@¥’TŽ; ÄÝIáå±ôzðÞ¾å¨ET	Ž·JT,V•Å§šÃð·0‰ ‡Ë>¸8™OõS¨ËÒ`äÙ¾A]Zíª
¤²²<C2B2>¯@M¢ÎÉ7 v;÷-hã˜é2§Ìyg‘pŸf¦1ýTáû^
+7˜

db/presets/54.bin

@@ -0,0 +1,3 @@
+PRST1x<EFBFBD>5ΞΝ
+Β0ΰW)γ5‡ώh­Ήϊ"%ΪU5)›νAΔww5xϊ–™9μΑ=BI
+v>Η%Α`q"ΔA»o<ώγK<CEB3>#'Ψ#6‡²ο†
'ƒ3ϋΫ]%-κ²4<C2B2>hvOΨVO·J„^Ι T°M­Φ<C2AD><CEA6>ΐκ"l3»L›ΩgΊΗ«<CE97>iτ“ώSαύ
<01><>5%

db/presets/55.bin

@@ -0,0 +1,4 @@
+PRST1xœMαÂ0Ð_A×5CZ ´™Q~!¨‘BR%î€ÿŽE¦gÝÝà7¢{˜
+ofŸiž
+ÇL9JõŸÞRH¹ÀœÐX{Ô½–¬µµ£ÆYášýýÁ‘ŠL:­&
+îÓËéVN0œWRˆ­dB3[Ä]e_é+‡ÊðcÉiö<69>.~’¿Z|¾¡	61

db/presets/56.bin

@@ -0,0 +1 @@
+PRST1xœ5ŽAƒ E¯b¾[¨U+WiŒ¡2¶¦`š¦éÝ’nxÌ›Y¼Œ|ùPÌÚÎ<C39A>¿ˆ60l2r&.?ýýlµuâ‚Rõ|àCt%Wuß5®n½Ýƒ!OjÎiùN¹ÜN¦‚¨¢35DÑ@¤é”Ñft}ÆùÀæì²jšVÓª#TSL<53>-)ËìZ³ôŒßQ•AÓ

db/presets/57.bin

@@ -0,0 +1 @@
+PRST1xњEО1В0Р« ПљЎiЎ ЂK „5)MЪФвоXНЂ—gщяБD72В‹lF—зВѓЙ‰pЋьoчR^@glOлаbpЛющ’И‹mУЬФлкЉ$ђдВС‚:ҐХљТЃ¬Іi/о+}еP9®L9=|а«ф‹пжg2д

db/presets/58.bin

@@ -0,0 +1,2 @@
+PRST1xœ=ÎÍ
+Â0àW‘é5‡ô?ìM"}	‰vÕBMJ’D|wSž¾afû†5O!rˆ;³zç

db/presets/59.bin

@@ -0,0 +1,3 @@
+PRST1x°Mна
+б0ЮW▒вз╘SzTЯ%D╓╨L╣m├┬ЬНfКе\╬ДOЫ ╦'а┌)С"┤ЬЙ°ВP3╔ ⌡©П}LЖ└Й8≈dуNЖр²╝╘©?8P√⌠Zk┘√╪{ц6р╨▒#,╖▒┌≥Жb
+k└%Л4╜

db/presets/6.bin

@@ -0,0 +1,2 @@
+PRST1xœMÎK
+Â0…ὧÜT£’tR$Ú«âMÉc âÞm<C39E>ˆ£þ39Oˆ»3,¦2Car¥p’¿rŽ!¦{ÀŠ¨ï‰0(œ’¿ÞŠpž‡Î…‘ƒ{À"WK„-©²‚hXMK•î;Ëú—6°¦±mìûSŠøèÇù’Æë

db/presets/60.bin

@@ -0,0 +1,4 @@
+PRST1xœMÎA‚0Ы˜ï¶‹R
É€KcŠŒBR[Òc¼»­l\½Éÿùɼáí“ANr˜ÙFÙ
+V+ÂÑçê?½b
+8ö½éj<EFBFBD>‹Â—Ç,žS.ŒÖ
+;ûµù´›<04>Ä<EFBFBD>|ªL½
uŨ)_ƒ

db/presets/62.bin

@@ -0,0 +1,3 @@
+PRST1xœ5ŽA‚0E¯B>Û.
+*š€KCªŒBRÚ¦c¼»ÅÙ¼7óÿb>ðv"0Í\D눙Š)¤8@!ZÙ’—xOºò.¤抲mµŒÜJ­W϶:n
+÷4¾ö4K¹ÖZ¡'gß0<C39F>¨]8ÀpZHÁW0ÕVðõÞô˜ÇŒSF“qθlˆ)<GGÝØË«¾?ð¹<

db/presets/7.bin

@@ -0,0 +1,3 @@
+PRST1xœMŽ1Â0Eïò»fp
+<EFBFBD>(K/<2F>
+­<EFBFBD>H!©Òt@ˆ»cÈÂô¾Ÿ¿%¿<>üƒá0†2F†Âìkå’þÕ˜c.ÜÝ0‘¸Î‘%œ.%Üî5ñ"•Þ…‰£J&RðkÍpµ¬¬<C2AC>´HA§e•6mÜÂÉQ2p_¹kØ7Øæ’¯!ò9Lò–Æû¼Ã1ó

db/presets/9.bin

@@ -0,0 +1,2 @@
+PRST1xœ%ÎK
+Ã0Ы”éÖ‹$ýâ«”ÜFnŽ›PJï^ÇÖæI£Í|Áf&hlFæÃ6¹HPXLŒ$œãÀù|d…~àhË WxŠ{O‘iÍ<69>®iFòæÝî»I1@GI¤À-tŽ¸«œ*çÊ¥r­Ü*÷Â"Á:Oƒs<>¶´ò”{

db/profile.json

@@ -1 +1 @@
-{"1": {"name": "Default", "tabs": ["1", "2"], "scenes": ["1", "2"], "palette": ["#FF0000", "#00FF00", "#0000FF", "#FFFF00", "#FF00FF", "#00FFFF", "#FFFFFF", "#000000"]}, "2": {"name": "test", "type": "tabs", "tabs": ["12", "13"], "scenes": [], "palette": ["#b93c3c", "#3cb961"], "color_palette": ["#b93c3c", "#3cb961"]}}
+{"1":{"name":"default","type":"zones","zones":["1","9","8","10"],"scenes":[],"palette_id":"1"},"2":{"name":"test","type":"zones","zones":["6","7"],"scenes":[],"palette_id":"12"},"3":{"name":"Winter","type":"zones","zones":["11","12"],"scenes":[],"palette_id":"14"}}

db/tab.json

@@ -1 +0,0 @@
-{"1": {"name": "Main", "names": ["1", "2", "3"], "presets": ["1", "2"]}, "2": {"name": "Accent", "names": ["4", "5"], "presets": ["2", "3"]}, "3": {"name": "", "names": [], "presets": []}, "4": {"name": "", "names": [], "presets": []}, "5": {"name": "", "names": [], "presets": []}, "6": {"name": "", "names": [], "presets": []}, "7": {"name": "", "names": [], "presets": []}, "8": {"name": "", "names": [], "presets": []}, "9": {"name": "", "names": [], "presets": []}, "10": {"name": "", "names": [], "presets": []}, "11": {"name": "", "names": [], "presets": []}, "12": {"name": "test2", "names": ["1"], "presets": [], "colors": ["#b93c3c", "#761e1e", "#ffffff"]}, "13": {"name": "test5", "names": ["1"], "presets": []}}

dev.py

@@ -1,53 +0,0 @@
-#!/usr/bin/env python3
-
-import subprocess
-import serial
-import sys
-
-print(sys.argv)
-
-# Extract port (first arg if it's not a command)
-commands = ["src", "lib", "ls", "reset", "follow", "db"]
-port = None
-if len(sys.argv) > 1 and sys.argv[1] not in commands:
-    port = sys.argv[1]
-
-
-for cmd in sys.argv[1:]:
-    print(cmd)
-    match cmd:
-        case "src":
-            if port:
-                subprocess.call(["mpremote", "connect", port, "fs", "cp", "-r", ".", ":" ], cwd="src")
-            else:
-                print("Error: Port required for 'src' command")
-        case "lib":
-            if port:
-                subprocess.call(["mpremote", "connect", port, "fs", "cp", "-r", "lib", ":" ])
-            else:
-                print("Error: Port required for 'lib' command")
-        case "ls":
-            if port:
-                subprocess.call(["mpremote", "connect", port, "fs", "ls", ":" ])
-            else:
-                print("Error: Port required for 'ls' command")
-        case "reset":
-            if port:
-                with serial.Serial(port, baudrate=115200) as ser:
-                    ser.write(b'\x03\x03\x04')
-            else:
-                print("Error: Port required for 'reset' command")
-        case "follow":
-            if port:
-                with serial.Serial(port, baudrate=115200) as ser:
-                    while True:
-                        if ser.in_waiting > 0:  # Check if there is data in the buffer
-                            data = ser.readline().decode('utf-8').strip()  # Read and decode the data
-                            print(data)
-            else:
-                print("Error: Port required for 'follow' command")
-        case "db":
-            if port:
-                subprocess.call(["mpremote", "connect", port, "fs", "cp", "-r", "db", ":" ])
-            else:
-                print("Error: Port required for 'db' command")

docs/API.md

@@ -1,504 +1,358 @@
-# LED Controller API Specification
+# LED Controller API
 
-**Base URL:** `http://device-ip/` or `http://192.168.4.1/` (when in AP mode)  
-**Protocol:** HTTP/1.1  
-**Content-Type:** `application/json`
+This document covers:
 
-## Presets API
+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 **ESP-NOW bridge** (WebSocket) to ESP32 peers and as **single JSON text messages** over the **outbound WebSocket** to **Wi-Fi** drivers (same logical fields).
 
-### GET /presets
+Default HTTP listen address: `0.0.0.0`. Port defaults to **80**; override with the **`PORT`** environment variable (see `pipenv run run`).
 
-List all presets.
+**Serial:** UART path and baud come from settings (defaults include `serial_port` such as `/dev/ttyS0` and `serial_baudrate`). **Wi-Fi drivers:** **UDP** on port **8766** is the **discovery** channel: each driver’s JSON hello (**`device_name`**, **MAC**, optional **`type`**) **creates or updates** that device in **`db/device.json`** (keyed by MAC); the Pi echoes the datagram. After a valid hello with **`v`:** **`"1"`**, the Pi also opens an **outbound WebSocket** to that IP (**`wifi_driver_ws_port`**, default **80**; **`wifi_driver_ws_path`**, default **`/ws`**) for v1 commands; presets are not pushed automatically on connect (use **Send Presets** / profile apply). The Pi may send periodic UDP **hello** nudges to known Wi‑Fi device IPs when the WebSocket is down (**`wifi_driver_hello_interval_s`** in settings).
+
+All JSON APIs use `Content-Type: application/json` for bodies and responses unless noted.
+
+---
+
+## UI behavior notes
+
+The main UI has two modes controlled by the mode toggle:
+
+- **Run mode**: optimized for operation (zone/preset selection and profile apply).
+- **Edit mode**: shows editing/management controls (zones, presets, patterns, colour palette, send presets, profile management actions, **Devices** registry for LED driver names/MACs, and related tools).
+
+Profiles are available in both modes, but behavior differs:
+
+- **Run mode**: profile **apply** only.
+- **Edit mode**: profile **create/clone/delete/apply**.
+
+`POST /presets/send` is wired to the **Send Presets** UI action, which is exposed in Edit mode.
+
+---
+
+## Session and scoping
+
+Several routes use **`@with_session`**: the server stores a **current profile** in the session (cookie). Endpoints that scope data to “the current profile” (notably **`/presets`**) only return or mutate presets whose `profile_id` matches that session value.
+
+Profiles are selected with **`POST /profiles/<id>/apply`**, which sets `current_profile` in the session.
+
+---
+
+## Static pages and assets
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | Main UI (`templates/index.html`) |
+| GET | `/settings/page` | Standalone settings page (`templates/settings.html`) |
+| GET | `/favicon.ico` | Empty response (204) |
+| GET | `/static/<path>` | Static files under `src/static/` |
+
+---
+
+## WebSocket: `/ws`
+
+Connect to **`ws://<host>:<port>/ws`**.
+
+- 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"}`.
+
+Wi-Fi devices are not targeted by `/ws` directly; use **`POST /presets/send`**, device routes, or **`POST /patterns/<name>/send`** as appropriate.
+
+---
+
+## HTTP API by resource
+
+Below, `<id>` values are string identifiers used by the JSON stores (numeric strings in practice).
+
+### Settings — `/settings`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/settings` | Full settings object (from `settings.json` / `Settings` model). |
+| PUT | `/settings/settings` | Merge keys into settings and save. Returns `{"message": "Settings updated successfully"}`. |
+| GET | `/settings/wifi/ap` | Saved Wi‑Fi AP fields: `saved_ssid`, `saved_password`, `saved_channel`, `active` (Pi: `active` is always false). |
+| POST | `/settings/wifi/ap` | Body: `ssid` (required), `password`, `channel` (1–11). Persists AP-related settings. |
+| GET | `/settings/page` | Serves `templates/settings.html`. |
+
+### Devices — `/devices`
+
+Registry in `db/device.json`: storage key **`<id>`** (string, e.g. `"1"`) maps to an object that always includes:
+
+| Field | Description |
+|-------|-------------|
+| **`id`** | Same as the storage key (stable handle for URLs). |
+| **`name`** | Shown in the UI and used in `select` keys. |
+| **`type`** | `led` (only value today; extensible). |
+| **`transport`** | `espnow` or `wifi`. |
+| **`address`** | For **`espnow`**: optional 12-character lowercase hex MAC. For **`wifi`**: optional IP or hostname string. |
+| **`default_pattern`**, **`zones`** | Optional. Legacy **`tabs`** may still appear in old files and is migrated away on load. |
+
+Existing records without `type` / `transport` / `id` are backfilled on load (`led`, `espnow`, and `id` = key).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/devices` | Map of device id → device object. |
+| GET | `/devices/<id>` | One device, 404 if missing. |
+| POST | `/devices` | Create. Body: **`name`** (required), **`type`** (default `led`), **`transport`** (default `espnow`), optional **`address`**, **`default_pattern`**, **`zones`**. Returns `{ "<id>": { ... } }`, 201. |
+| PUT | `/devices/<id>` | Partial update. **`name`** cannot be cleared. **`id`** in the body is ignored. **`type`** / **`transport`** validated; **`address`** normalised for the resulting transport. |
+| DELETE | `/devices/<id>` | Remove device. |
+
+### Profiles — `/profiles`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/profiles` | `{"profiles": {...}, "current_profile_id": "<id>"}`. Ensures a default current profile when possible. |
+| GET | `/profiles/current` | `{"id": "...", "profile": {...}}` |
+| GET | `/profiles/<id>` | Single profile. If `<id>` is `current`, same as `/profiles/current`. |
+| POST | `/profiles` | Create profile. Body may include `name` and other fields. Optional `seed_dj_zone` (request-only) seeds a DJ zone + presets. New profiles always get a populated `default` zone. Returns `{ "<id>": { ... } }` with status 201. |
+| POST | `/profiles/<id>/apply` | Sets session current profile to `<id>`. |
+| POST | `/profiles/<id>/clone` | Clone profile (zones, palettes, presets). Body may include `name`. |
+| PUT | `/profiles/current` | Update the current profile (from session). |
+| PUT | `/profiles/<id>` | Update profile by id. |
+| DELETE | `/profiles/<id>` | Delete profile. |
+
+### Presets — `/presets`
+
+Scoped to **current profile** in session (see above).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/presets` | Map of preset id → preset object for the current profile only. |
+| GET | `/presets/<id>` | One preset, 404 if missing or wrong profile. |
+| POST | `/presets` | Create preset; server assigns id and sets `profile_id`. Body fields stored on the preset. Returns `{ "<id>": { ... } }`, 201. |
+| PUT | `/presets/<id>` | Update preset (must belong to current profile). |
+| DELETE | `/presets/<id>` | Delete preset. |
+| POST | `/presets/send` | Push presets to the LED driver over the configured transport (see below). |
+
+**`POST /presets/send` body:**
 
-**Response:** `200 OK`
 ```json
 {
-  "preset1": {
-    "name": "preset1",
-    "pattern": "on",
-    "colors": [[255, 0, 0]],
-    "delay": 100,
-    "n1": 0,
-    "n2": 0,
-    "n3": 0,
-    "n4": 0,
-    "n5": 0,
-    "n6": 0,
-    "n7": 0,
-    "n8": 0
+  "preset_ids": ["1", "2"],
+  "save": true,
+  "default": "1",
+  "destination_mac": "aabbccddeeff"
+}
+```
+
+- **`preset_ids`** (or **`ids`**): non-empty list of preset ids to include.
+- **`save`**: if true, the outgoing message includes `"save": true` so the driver may persist presets (default true).
+- **`default`**: optional preset id string; forwarded as top-level `"default"` in the driver message (startup selection on device).
+- **`destination_mac`** (or **`to`**): optional 12-character hex MAC for unicast; omitted uses the transport default (e.g. broadcast).
+
+Response on success includes `presets_sent`, `messages_sent` (chunking splits payloads so each JSON string stays ≤ 240 bytes).
+
+Stored preset records can include:
+
+- `colors`: resolved hex colours for editor/display.
+- `palette_refs`: optional array of palette indexes parallel to `colors`. If a slot contains an integer index, the colour is linked to the current profile palette at that index.
+
+### Zones — `/zones`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/zones` | `zones` (map of zone id → zone object), `zone_order`, `current_zone_id`, `profile_id` for the session-backed profile. |
+| GET | `/zones/current` | Current zone from cookie/session. |
+| POST | `/zones` | Create zone; optional JSON `name`, `names`, `presets`; can append to current profile’s zone list. |
+| GET | `/zones/<id>` | Zone JSON. |
+| PUT | `/zones/<id>` | Update zone. |
+| DELETE | `/zones/<id>` | Delete zone; can delete `current` to remove the active zone; updates profile zone list. |
+| POST | `/zones/<id>/set-current` | Sets `current_zone` cookie. |
+| POST | `/zones/<id>/clone` | Clone zone into current profile. |
+
+### Palettes — `/palettes`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/palettes` | Map of id → colour list. |
+| GET | `/palettes/<id>` | `{"colors": [...], "id": "<id>"}` |
+| POST | `/palettes` | Body may include `colors`. Returns palette object with `id`, 201. |
+| PUT | `/palettes/<id>` | Update colours (`name` ignored). |
+| DELETE | `/palettes/<id>` | Delete palette. |
+
+### Groups — `/groups`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/groups` | All groups. |
+| GET | `/groups/<id>` | One group. |
+| POST | `/groups` | Create; optional `name` and fields. |
+| PUT | `/groups/<id>` | Update. |
+| DELETE | `/groups/<id>` | Delete. |
+
+### Scenes — `/scenes`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/scenes` | All scenes. |
+| GET | `/scenes/<id>` | One scene. |
+| POST | `/scenes` | Create (body JSON stored on scene). |
+| PUT | `/scenes/<id>` | Update. |
+| DELETE | `/scenes/<id>` | Delete. |
+
+### Sequences — `/sequences`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/sequences` | All sequences. |
+| GET | `/sequences/<id>` | One sequence. |
+| POST | `/sequences` | Create; may use `group_name`, `presets` in body. |
+| PUT | `/sequences/<id>` | Update. |
+| DELETE | `/sequences/<id>` | Delete. |
+
+### Patterns — `/patterns`
+
+Pattern metadata lives in **`db/pattern.json`**; driver source files live under **`led-driver/src/patterns/`**. Several routes expose a **runtime map** (metadata merged with on-disk `.py` names so new files appear in menus).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/patterns` | Runtime pattern map (object keyed by pattern id). |
+| GET | `/patterns/definitions` | Same runtime map (intended for UI “definitions” clients). |
+| GET | `/patterns/ota/manifest` | JSON `{"files":[{"name":"blink.py","url":"http://<Host>/patterns/ota/file/blink.py"},...]}` for OTA pulls. Requires **`Host`** header. |
+| GET | `/patterns/ota/file/<name>` | Raw **`.py`** source for one driver pattern (`name` must be a safe filename, e.g. `rainbow.py`). |
+| POST | `/patterns/<name>/send` | Push a **manifest** JSON line to **Wi-Fi** devices so they pull one pattern file over HTTP. Body may include **`device_id`** to target one device; otherwise all Wi-Fi devices with an **`address`** are tried. **`<name>`** may be with or without `.py`. |
+| POST | `/patterns/upload` | Body JSON: **`name`**, **`code`**, optional **`overwrite`** (default true). Writes **`led-driver/src/patterns/<name>.py`**. |
+| POST | `/patterns/driver` | Body JSON: **`name`** (identifier), **`code`**, optional metadata (`min_delay`, `max_delay`, `max_colors`, `n1`…`n8`, **`overwrite`**). Creates/updates both the **`.py`** file and **`db/pattern.json`** via the Pattern model. |
+| GET | `/patterns/<id>` | One pattern record from the Pattern model (metadata only). |
+| POST | `/patterns` | Create (`name`, optional `data`). |
+| PUT | `/patterns/<id>` | Update. |
+| DELETE | `/patterns/<id>` | Delete. |
+
+**Devices — pattern OTA push**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/devices/<id>/patterns/push` | Wi-Fi only. Asks the driver at **`address`** to pull pattern files from this server. Optional body **`manifest`**: either a **URL string** pointing at a manifest JSON document, or a **manifest object** (same shape as in driver messages). If omitted, a default manifest is built from the request **`Host`** header. |
+
+---
+
+## LED driver message format (transport / ESP-NOW / Wi-Fi)
+
+Messages are JSON objects. The Pi **`build_message()`** helper (`src/util/espnow_message.py`) produces the same shape sent over serial and forwarded by the ESP32 bridge, and the same logical object can be sent as a **single JSON text message** to a Wi-Fi driver over the **WebSocket**.
+
+### Top-level fields
+
+```json
+{
+  "v": "1",
+  "presets": { },
+  "select": { },
+  "save": true,
+  "default": "preset_id",
+  "b": 255
+}
+```
+
+- **`v`** (required): Must be `"1"` or the driver ignores the message.
+- **`presets`**: Map of **preset id** (string) → preset object (see below). Optional **`name`** field on each value is accepted for display; the driver keys presets by map key.
+- **`select`**: Map of **device name** (as in device settings) → `[ "preset_id" ]` or `[ "preset_id", step ]`.
+- **`save`**: If present (e.g. true), the driver may persist presets to flash after applying.
+- **`default`**: Preset id string to use as startup default on the device.
+- **`b`**: Optional **global** brightness 0–255 (driver applies this in addition to per-preset brightness).
+
+### Preset object (wire / driver keys)
+
+On the wire, presets use **short keys** (saves space in the ≤240-byte chunks):
+
+| Key | Meaning | Notes |
+|-----|---------|--------|
+| `p` | Pattern id | `off`, `on`, `blink`, `rainbow`, `pulse`, `transition`, `chase`, `circle` |
+| `c` | Colours | Array of `"#RRGGBB"` hex strings; converted to RGB on device |
+| `d` | Delay ms | Default 100 |
+| `b` | Preset brightness | 0–255; combined with global `b` on the device |
+| `a` | Auto | `true`: run continuously; `false`: one step/cycle per “beat” |
+| `n1`–`n6` | Pattern parameters | See below |
+
+The HTTP app’s **`POST /presets/send`** path builds this from stored presets via **`build_preset_dict()`** (long names like `pattern` / `colors` in the DB are translated to `p` / `c` / …).
+
+### Pattern-specific parameters (`n1`–`n6`)
+
+#### Rainbow
+- **`n1`**: Step increment on the colour wheel per update (default 1).
+
+#### Pulse
+- **`n1`**: Attack (fade in) ms  
+- **`n2`**: Hold ms  
+- **`n3`**: Decay (fade out) ms  
+- **`d`**: Off time between pulses ms  
+
+#### Transition
+- **`d`**: Transition duration ms  
+
+#### Chase
+- **`n1`**: LEDs with first colour  
+- **`n2`**: LEDs with second colour  
+- **`n3`**: Movement on even steps (may be negative)  
+- **`n4`**: Movement on odd steps (may be negative)  
+
+#### Circle
+- **`n1`**: Head speed (LEDs/s)  
+- **`n2`**: Max length  
+- **`n3`**: Tail speed (LEDs/s)  
+- **`n4`**: Min length  
+
+### Select messages
+
+```json
+{
+  "select": {
+    "device_name": ["preset_id"],
+    "other_device": ["preset_id", 10]
   }
 }
 ```
 
-### GET /presets/{name}
+- One element: select preset; step behavior follows driver rules (reset on `off`, etc.).
+- Two elements: explicit **step** for sync.
 
-Get a specific preset by name.
+### Beat and sync behavior
+
+- Sending **`select`** again with the **same** preset name acts as a **beat** (advances manual patterns / restarts generators per driver logic).
+- Choosing **`off`** resets step as a sync point; then selecting a pattern aligns step 0 across devices unless a step is passed explicitly.
+
+### Example (compact preset map)
 
-**Response:** `200 OK`
 ```json
 {
-  "name": "preset1",
-  "pattern": "on",
-  "colors": [[255, 0, 0]],
-  "delay": 100,
-  "n1": 0,
-  "n2": 0,
-  "n3": 0,
-  "n4": 0,
-  "n5": 0,
-  "n6": 0,
-  "n7": 0,
-  "n8": 0
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Preset not found"
-}
-```
-
-### POST /presets
-
-Create a new preset.
-
-**Request Body:**
-```json
-{
-  "name": "preset1",
-  "pattern": "on",
-  "colors": [[255, 0, 0]],
-  "delay": 100,
-  "n1": 0,
-  "n2": 0,
-  "n3": 0,
-  "n4": 0,
-  "n5": 0,
-  "n6": 0,
-  "n7": 0,
-  "n8": 0
-}
-```
-
-**Response:** `201 Created` - Returns the created preset
-
-**Response:** `400 Bad Request`
-```json
-{
-  "error": "Name is required"
-}
-```
-
-**Response:** `409 Conflict`
-```json
-{
-  "error": "Preset already exists"
-}
-```
-
-### PUT /presets/{name}
-
-Update an existing preset.
-
-**Request Body:**
-```json
-{
-  "delay": 200,
-  "colors": [[0, 255, 0]]
-}
-```
-
-**Response:** `200 OK` - Returns the updated preset
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Preset not found"
-}
-```
-
-### DELETE /presets/{name}
-
-Delete a preset.
-
-**Response:** `200 OK`
-```json
-{
-  "message": "Preset deleted successfully"
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Preset not found"
-}
-```
-
-## Profiles API
-
-### GET /profiles
-
-List all profiles.
-
-**Response:** `200 OK`
-```json
-{
-  "profile1": {
-    "name": "profile1",
-    "description": "Profile description",
-    "scenes": []
+  "v": "1",
+  "save": true,
+  "presets": {
+    "1": {
+      "name": "Red blink",
+      "p": "blink",
+      "c": ["#FF0000"],
+      "d": 200,
+      "b": 255,
+      "a": true,
+      "n1": 0, "n2": 0, "n3": 0, "n4": 0, "n5": 0, "n6": 0
+    }
+  },
+  "select": {
+    "living-room": ["1"]
   }
 }
 ```
 
-### GET /profiles/{name}
+---
 
-Get a specific profile by name.
+## Processing summary (driver)
 
-**Response:** `200 OK`
-```json
-{
-  "name": "profile1",
-  "description": "Profile description",
-  "scenes": []
-}
-```
+1. Reject if `v != "1"`.
+2. Apply optional top-level **`b`** (global brightness).
+3. For each entry in **`presets`**, normalize colours and upsert preset by id.
+4. If this device’s **`name`** appears in **`select`**, run selection (optional step).
+5. If **`default`** is set, store startup preset id.
+6. If **`save`** is set, persist presets.
 
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Profile not found"
-}
-```
+---
 
-### POST /profiles
+## Error handling (HTTP)
 
-Create a new profile.
+Controllers typically return JSON with an **`error`** string and 4xx/5xx status codes. Invalid JSON bodies often yield `{"error": "Invalid JSON"}`.
 
-**Request Body:**
-```json
-{
-  "name": "profile1",
-  "description": "Profile description",
-  "scenes": []
-}
-```
+---
 
-**Response:** `201 Created` - Returns the created profile
+## Notes
 
-**Response:** `400 Bad Request`
-```json
-{
-  "error": "Name is required"
-}
-```
-
-**Response:** `409 Conflict`
-```json
-{
-  "error": "Profile already exists"
-}
-```
-
-### PUT /profiles/{name}
-
-Update an existing profile.
-
-**Request Body:**
-```json
-{
-  "description": "Updated description"
-}
-```
-
-**Response:** `200 OK` - Returns the updated profile
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Profile not found"
-}
-```
-
-### DELETE /profiles/{name}
-
-Delete a profile.
-
-**Response:** `200 OK`
-```json
-{
-  "message": "Profile deleted successfully"
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Profile not found"
-}
-```
-
-## Scenes API
-
-### GET /scenes
-
-List all scenes. Optionally filter by profile using query parameter.
-
-**Query Parameters:**
-- `profile` (optional): Filter scenes by profile name
-
-**Example:** `GET /scenes?profile=profile1`
-
-**Response:** `200 OK`
-```json
-{
-  "profile1:scene1": {
-    "name": "scene1",
-    "profile_name": "profile1",
-    "description": "Scene description",
-    "transition_time": 0,
-    "devices": [
-      {"device_name": "device1", "preset_name": "preset1"},
-      {"device_name": "device2", "preset_name": "preset2"}
-    ]
-  }
-}
-```
-
-### GET /scenes/{profile_name}/{scene_name}
-
-Get a specific scene.
-
-**Response:** `200 OK`
-```json
-{
-  "name": "scene1",
-  "profile_name": "profile1",
-  "description": "Scene description",
-  "transition_time": 0,
-  "devices": [
-    {"device_name": "device1", "preset_name": "preset1"},
-    {"device_name": "device2", "preset_name": "preset2"}
-  ]
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Scene not found"
-}
-```
-
-### POST /scenes
-
-Create a new scene.
-
-**Request Body:**
-```json
-{
-  "name": "scene1",
-  "profile_name": "profile1",
-  "description": "Scene description",
-  "transition_time": 0,
-  "devices": [
-    {"device_name": "device1", "preset_name": "preset1"},
-    {"device_name": "device2", "preset_name": "preset2"}
-  ]
-}
-```
-
-**Response:** `201 Created` - Returns the created scene
-
-**Response:** `400 Bad Request`
-```json
-{
-  "error": "Name is required"
-}
-```
-or
-```json
-{
-  "error": "Profile name is required"
-}
-```
-
-**Response:** `409 Conflict`
-```json
-{
-  "error": "Scene already exists"
-}
-```
-
-### PUT /scenes/{profile_name}/{scene_name}
-
-Update an existing scene.
-
-**Request Body:**
-```json
-{
-  "transition_time": 500,
-  "description": "Updated description"
-}
-```
-
-**Response:** `200 OK` - Returns the updated scene
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Scene not found"
-}
-```
-
-### DELETE /scenes/{profile_name}/{scene_name}
-
-Delete a scene.
-
-**Response:** `200 OK`
-```json
-{
-  "message": "Scene deleted successfully"
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Scene not found"
-}
-```
-
-### POST /scenes/{profile_name}/{scene_name}/devices
-
-Add a device assignment to a scene.
-
-**Request Body:**
-```json
-{
-  "device_name": "device1",
-  "preset_name": "preset1"
-}
-```
-
-**Response:** `200 OK` - Returns the updated scene
-
-**Response:** `400 Bad Request`
-```json
-{
-  "error": "Device name and preset name are required"
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Scene not found"
-}
-```
-
-### DELETE /scenes/{profile_name}/{scene_name}/devices/{device_name}
-
-Remove a device assignment from a scene.
-
-**Response:** `200 OK` - Returns the updated scene
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Scene not found"
-}
-```
-
-## Patterns API
-
-### GET /patterns
-
-Get the list of available pattern names.
-
-**Response:** `200 OK`
-```json
-["on", "bl", "cl", "rb", "sb", "o"]
-```
-
-### POST /patterns
-
-Add a new pattern name to the list.
-
-**Request Body:**
-```json
-{
-  "name": "new_pattern"
-}
-```
-
-**Response:** `201 Created` - Returns the updated list of patterns
-```json
-["on", "bl", "cl", "rb", "sb", "o", "new_pattern"]
-```
-
-**Response:** `400 Bad Request`
-```json
-{
-  "error": "Name is required"
-}
-```
-
-**Response:** `409 Conflict`
-```json
-{
-  "error": "Pattern already exists"
-}
-```
-
-### DELETE /patterns/{name}
-
-Remove a pattern name from the list.
-
-**Response:** `200 OK`
-```json
-{
-  "message": "Pattern deleted successfully"
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Pattern not found"
-}
-```
-
-## Error Responses
-
-All endpoints may return the following error responses:
-
-**400 Bad Request** - Invalid request data
-```json
-{
-  "error": "Error message"
-}
-```
-
-**404 Not Found** - Resource not found
-```json
-{
-  "error": "Resource not found"
-}
-```
-
-**409 Conflict** - Resource already exists
-```json
-{
-  "error": "Resource already exists"
-}
-```
-
-**500 Internal Server Error** - Server error
-```json
-{
-  "error": "Error message"
-}
-```
+- **Human-readable preset fields** (`pattern`, `colors`, `delay`, …) are fine in the **web app / database**; the **send path** converts them to **`p` / `c` / `d`** for the driver.
+- For a copy of the older long-key reference, see **`led-driver/docs/API.md`** in this repo (conceptually the same behavior; wire format prefers short keys).

docs/SPECIFICATION.md

@@ -44,7 +44,7 @@ The LED Driver system is a MicroPython-based application for controlling LED str
 - Pattern configuration and control (patterns run on remote devices)
 - Real-time brightness and speed control
 - Global brightness setting (system-wide brightness multiplier)
-- Multi-color support with customizable color palettes
+- Multi-colour support with customizable colour palettes
 - Device grouping for synchronized control
 - Preset system for saving and loading pattern configurations
 - Profile and Scene system for complex lighting setups
@@ -239,7 +239,7 @@ Primary interface for real-time LED control and monitoring.
 - **Grid Layout:** 4-column responsive grid
   - Pattern Selection Card
   - Brightness & Speed Card
-  - Color Selection Card
+  - Colour Selection Card
   - Device Status Card
 - **Action Bar:** Apply and Save buttons
 
@@ -273,12 +273,12 @@ Primary interface for real-time LED control and monitoring.
 - **Default:** 100ms
 - **Step:** 10ms increments
 
-**Color Selection**
-- **Type:** Color picker inputs (HTML5 color input)
-- **Quantity:** Multiple colors (minimum 2, expandable)
-- **Format:** Hex color codes (e.g., #FF0000)
-- **Display:** Large color swatches (60x60px)
-- **Action:** "Add Color" button for additional colors
+**Colour Selection**
+- **Type:** Colour picker inputs (HTML5 colour input)
+- **Quantity:** Multiple colours (minimum 2, expandable)
+- **Format:** Hex colour codes (e.g., #FF0000)
+- **Display:** Large colour swatches (60x60px)
+- **Action:** "Add Colour" button for additional colours
 
 **Device Status List**
 - **Type:** List of connected devices
@@ -295,7 +295,7 @@ Primary interface for real-time LED control and monitoring.
 - **Save to Device:** Persist settings to device storage
 
 #### Design Specifications
-- **Color Scheme:** Purple gradient background (#667eea to #764ba2)
+- **Colour Scheme:** Purple gradient background (#667eea to #764ba2)
 - **Cards:** White background, rounded corners (12px), shadow
 - **Hover Effects:** Card lift (translateY -2px), increased shadow
 - **Typography:** System font stack, 1.25rem headings
@@ -350,10 +350,10 @@ Manage connected devices and create/manage device groups.
 
 #### Layout
 - **Header:** Title with "Add Device" button
-- **Tabs:** Devices and Groups tabs
-- **Content Area:** Tab-specific content
+- **Zones:** Devices and Groups zones (zone buttons / zone strip)
+- **Content Area:** Zone-specific content
 
-#### Devices Tab
+#### Devices Zone
 
 **Device List**
 - **Display:** List of all known devices
@@ -375,7 +375,7 @@ Manage connected devices and create/manage device groups.
 - **Actions:** Cancel, Save
 - **Note:** Only one master device per system. Adding a new master will demote existing master to slave.
 
-#### Groups Tab
+#### Groups Zone
 
 **Group List**
 - **Display:** List of all device groups
@@ -397,7 +397,7 @@ Manage connected devices and create/manage device groups.
 - **Actions:** Cancel, Create
 
 #### Design Specifications
-- **Tab Style:** Active tab has purple background, white text
+- **Zone Style:** Active zone has purple background, white text
 - **List Items:** Bordered cards with hover effects
 - **Modal:** Centered overlay with white card, shadow
 - **Status Badges:** Colored pills (green for online, red for offline)
@@ -509,7 +509,7 @@ Comprehensive device configuration interface.
 - Device Name (text input)
 - LED Pin (number input, 0-40)
 - Number of LEDs (number input, 1-1000)
-- Color Order (visual selector with 6 options: RGB, RBG, GRB, GBR, BRG, BGR)
+- Colour Order (visual selector with 6 options: RGB, RBG, GRB, GBR, BRG, BGR)
 
 **2. Pattern Settings**
 - Pattern (dropdown selection)
@@ -577,16 +577,16 @@ Comprehensive device configuration interface.
 - Range: Slider with real-time value display
 - Select: Dropdown menu
 - Checkbox: Toggle switch
-- Color: HTML5 color picker
+- Colour: HTML5 colour picker
 
-**Color Order Selector**
+**Colour Order Selector**
 - **Type:** Visual button grid
 - **Options:** RGB, RBG, GRB, GBR, BRG, BGR
-- **Display:** Color boxes showing order (R=red, G=green, B=blue)
+- **Display:** Colour boxes showing order (R=red, G=green, B=blue)
 - **Selection:** Single selection with visual feedback
 
 #### Design Specifications
-- **Section Headers:** Purple color (#667eea), 1.5rem font, bottom border
+- **Section Headers:** Purple colour (#667eea), 1.5rem font, bottom border
 - **Form Groups:** 24px spacing between fields
 - **Labels:** Bold, 500 weight, dark gray (#333)
 - **Help Text:** Small gray text below inputs
@@ -611,7 +611,7 @@ Save, load, and manage preset configurations for quick pattern switching.
 Each preset card displays:
 - **Name:** Preset name (bold, 1.25rem)
 - **Pattern Badge:** Current pattern type
-- **Color Preview:** Swatches showing preset colors
+- **Colour Preview:** Swatches showing preset colours
 - **Quick Info:** Delay and brightness values
 - **Actions:** Apply, Edit, Delete buttons
 
@@ -620,7 +620,7 @@ Each preset card displays:
 **Fields:**
 - Preset Name (text input, required)
 - Pattern (dropdown selection)
-- Colors (multiple color pickers, minimum 2)
+- Colours (multiple colour pickers, minimum 2)
 - Delay (slider, 10-1000ms)
 - Step Offset (number input, optional, default: 0)
   - Tooltip: "Step offset for group synchronization. Applied per device when preset is used in a group."
@@ -667,7 +667,7 @@ Each preset card displays:
 #### Design Specifications
 - **Card Style:** White background, rounded corners, shadow
 - **Pattern Badge:** Colored pill with pattern name
-- **Color Swatches:** 40x40px squares in card header
+- **Colour Swatches:** 40x40px squares in card header
 - **Hover Effect:** Card lift, border highlight
 - **Selected State:** Purple border, subtle background tint
 
@@ -681,7 +681,7 @@ Patterns are configured on the controller and sent to remote devices for executi
 
 - **Pattern Type:** Identifier for the pattern (e.g., "on", "off", "blink", "chase", "pulse", "rainbow", etc.)
 - **Pattern Parameters:** Numeric parameters (N1-N8) that configure pattern-specific behavior
-- **Colors:** Color palette for the pattern
+- **Colours:** Colour palette for the pattern
 - **Timing:** Delay and speed settings
 
 **Note:** Pattern execution happens on the remote devices. The controller sends configuration commands to devices.
@@ -698,7 +698,7 @@ Pattern-specific numeric parameters:
 
 #### Overview
 
-Presets allow users to save complete pattern configurations for quick recall and application. A preset encapsulates all pattern settings including pattern type, colors, timing, and all pattern parameters.
+Presets allow users to save complete pattern configurations for quick recall and application. A preset encapsulates all pattern settings including pattern type, colours, timing, and all pattern parameters.
 
 **Note:** Presets are optional. Devices can be controlled directly without presets.
 
@@ -708,7 +708,7 @@ A preset contains the following fields:
 
 - **name** (string, required): Unique identifier for the preset
 - **pattern** (string, required): Pattern type identifier (sent to remote devices)
-- **colors** (array of strings, required): Array of hex color codes (minimum 2 colors)
+- **colours** (array of strings, required): Array of hex colour codes (minimum 2 colours)
 - **delay** (integer, required): Delay in milliseconds (10-1000)
 - **n1** (integer, optional): Pattern parameter 1 (0-255, default: 0)
 - **n2** (integer, optional): Pattern parameter 2 (0-255, default: 0)
@@ -889,7 +889,7 @@ A preset contains the following fields:
 #### Group Properties
 - **Name:** Unique group identifier
 - **Devices:** List of device names (can include master and/or slaves)
-- **Settings:** Pattern, delay, colors
+- **Settings:** Pattern, delay, colours
 - **Step Offset:** Per-device step offset sent to devices for synchronized patterns (integer, can be negative)
   - Each device in group can receive different step offset
   - Creates wave/chase effect across multiple LED strips
@@ -953,7 +953,7 @@ Byte 1: Flags (bit 0: names, bit 1: groups, bit 2: settings, bit 3: save)
 |-----|------|-------------|--------------|
 | `pt` | string | Pattern type | on, off, blink, chase, circle, pulse, rainbow, transition |
 | `pm` | string | Pattern mode | auto, single_shot |
-| `cl` | array | Colors (hex strings) | Array of hex color codes |
+| `cl` | array | Colours (hex strings) | Array of hex colour codes |
 | `br` | int | Global brightness | 0-100 |
 | `dl` | int | Delay (ms) | 10-1000 |
 | `n1` | int | Parameter 1 | 0-255 |
@@ -966,7 +966,7 @@ Byte 1: Flags (bit 0: names, bit 1: groups, bit 2: settings, bit 3: save)
 | `n8` | int | Parameter 8 | 0-255 |
 | `led_pin` | int | GPIO pin | 0-40 |
 | `num_leds` | int | LED count | 1-1000 |
-| `color_order` | string | Color order | rgb, rbg, grb, gbr, brg, bgr |
+| `color_order` | string | Colour order | rgb, rbg, grb, gbr, brg, bgr |
 | `name` | string | Device name | Any string |
 | `brightness` | int | Global brightness | 0-100 |
 | `delay` | int | Delay | 10-1000 |
@@ -1247,7 +1247,7 @@ CREATE TABLE IF NOT EXISTS presets (
 **Preset Fields:**
 - `name` (string, required): Unique preset identifier
 - `pattern` (string, required): Pattern type
-- `colors` (array of strings, required): Hex color codes (minimum 2)
+- `colors` (array of strings, required): Hex colour codes (minimum 2)
 - `delay` (integer, required): Delay in milliseconds (10-1000)
 - `n1` through `n8` (integer, optional): Pattern parameters (0-255, default: 0)
 
@@ -1289,7 +1289,7 @@ CREATE TABLE IF NOT EXISTS presets (
 
 **POST /api/presets**
 - Create a new preset
-- Body: Preset object (name, pattern, colors, delay, n1-n8)
+- Body: Preset object (name, pattern, colours, delay, n1-n8)
 - Response: Created preset object
 
 **GET /api/presets/{name}**
@@ -1495,7 +1495,7 @@ peak_mem = usqlite.mem_peak()
 
 ### Flow 2: Create Device Group
 
-1. User navigates to Device Management → Groups tab
+1. User navigates to Device Management → Groups zone
 2. User clicks "Create Group", enters name, selects pattern/settings
 3. User selects devices to add (can include master), clicks "Create"
 4. Group appears in list
@@ -1506,7 +1506,7 @@ peak_mem = usqlite.mem_peak()
 
 1. User navigates to Settings page
 2. User modifies settings in sections:
-   - Basic Settings (pin, LED count, color order)
+   - Basic Settings (pin, LED count, colour order)
    - Pattern Settings (pattern, delay)
    - Global Brightness
    - Advanced Settings (N1-N8 parameters)
@@ -1519,7 +1519,7 @@ peak_mem = usqlite.mem_peak()
 ### Flow 4: Multi-Device Control
 
 1. User selects multiple devices or a group
-2. User changes pattern/colors/global brightness
+2. User changes pattern/colours/global brightness
 3. User clicks "Apply Settings"
 4. System sends message targeting selected devices/groups
 5. All targeted devices update simultaneously
@@ -1585,7 +1585,7 @@ peak_mem = usqlite.mem_peak()
 
 ## Design Guidelines
 
-### Color Palette
+### Colour Palette
 
 - **Primary:** Purple gradient `#667eea` to `#764ba2`, Light gradient `#f5f7fa` to `#c3cfe2`
 - **UI:** Primary `#667eea`, Hover `#5568d3`, Secondary `#e0e0e0`
@@ -1612,8 +1612,8 @@ peak_mem = usqlite.mem_peak()
 - Disabled: 50% opacity, no pointer events
 
 **Inputs:**
-- Focus: Border color changes to primary purple
-- Hover: Slight border color change
+- Focus: Border colour changes to primary purple
+- Hover: Slight border colour change
 - Error: Red border
 
 **Cards:**
@@ -1738,7 +1738,7 @@ peak_mem = usqlite.mem_peak()
 - Validation
 
 **Preset Management:**
-- Preset creation with all fields (name, pattern, colors, delay, n1-n8)
+- Preset creation with all fields (name, pattern, colours, delay, n1-n8)
 - Preset loading and application
 - Preset editing and deletion
 - Name uniqueness validation
@@ -1758,7 +1758,7 @@ peak_mem = usqlite.mem_peak()
 - Configuration parameters are properly formatted
 
 **Preset Application:**
-- Preset loads all parameters correctly (pattern, colors, delay, n1-n8)
+- Preset loads all parameters correctly (pattern, colours, delay, n1-n8)
 - Preset applies to single device
 - Preset applies to device group
 - Preset values match saved configuration
@@ -1774,7 +1774,7 @@ peak_mem = usqlite.mem_peak()
 - Buttons respond to clicks
 - Sliders update values
 - Modals open/close
-- Tabs switch correctly
+- Zone buttons switch correctly
 - Preset selector works
 - Preset creation form validates input
 - Preset cards display correctly

docs/espnow-architecture.md

@@ -0,0 +1,184 @@
+# 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).
+
+**Pi ↔ bridge WebSocket:** v1 **devices envelope** (JSON) — see [espnow-sender/msg.json](../espnow-sender/msg.json). **ESP-NOW over the air:** JSON driver payloads (≤250 bytes) or legacy binary (`0x4C` wire). The Pi web UI and `db/*.json` 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 (auto-reconnect); device registry; builds devices envelope |
+| **Bridge** | [`espnow-sender/`](../espnow-sender/) | WebSocket **server** `/ws`; routes envelope per MAC; 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": 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**: 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).
+
+---
+
+## 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 sends a **groups** envelope (`set_groups: true`) unicast to that MAC.
+5. Driver stores group ids in RAM (`device_groups`) for filtering.
+6. Pi bridge client **reconnects** automatically if the WebSocket drops (2 s backoff).
+
+If the Pi or bridge is not up yet, the driver re-sends **ANNOUNCE** periodically until **GROUPS** arrives.
+
+---
+
+## Devices envelope (Pi → bridge)
+
+```json
+{
+  "v": "1",
+  "dv": {
+    "ff:ff:ff:ff:ff:ff": {
+      "p": { "2": { "p": "on", "c": ["#FFFFFF"], "a": true } },
+      "s": ["2", 0],
+      "g": ["5", "18"],
+      "sg": false,
+      "sv": true
+    }
+  }
+}
+```
+
+Short wire names (long names still accepted on receive): `dv`=devices, `p`=presets, `s`=select (`["preset_id", step?]` — no device name), `g`=groups, `sg`=set_groups, `sv`=save, `df`=default; preset fields `p/c/d/b/a/bg/n1…`.
+
+| `set_groups` | Destination | Bridge | Driver |
+|--------------|-------------|--------|--------|
+| `true` | any | Unicast only (expand `ff:ff:…` to all known peers) | `groups_replace`, then apply body |
+| `false` | `ff:ff:ff:ff:ff:ff` | ESP-NOW air broadcast | Apply only if device is in `groups` |
+| `false` | specific MAC | Unicast | Same group filter |
+
+Legacy raw payloads (binary wire or plain v1 JSON without `devices`) are still **broadcast** by the bridge.
+
+## Sending presets and commands
+
+1. UI or API triggers a send (e.g. `POST /presets/push`).
+2. Pi builds a **devices envelope** (or legacy binary) and sends it on the bridge WebSocket.
+3. Bridge routes each MAC entry to unicast or ESP-NOW broadcast per `set_groups`.
+4. Driver `process_data` applies presets, select (`[preset_id, step?]`; legacy name map still accepted), brightness, etc.
+
+---
+
+## 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) |

docs/espnow-binary-protocol.md

@@ -0,0 +1,114 @@
+# 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 |
+| `0x05` | `PING_REQ` | Controller → broadcast |
+| `0x06` | `PING_RSP` | Driver → controller (unicast) |
+| `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.
+
+### 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 |
+|-------|------|
+| 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.

docs/help.md

@@ -0,0 +1,114 @@
+# 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 **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**.
+
+Figures below are **schematic** (layout and ideas), not pixel-perfect screenshots.
+
+---
+
+## Run mode and Edit mode
+
+The header has a mode toggle (desktop and mobile menu). The **label on the button is the mode you switch to** when you press it.
+
+![Schematic: zone buttons on the left; Profiles, Zones, Presets, Patterns, and the mode toggle on the right (example shows Edit mode with “Run mode” on the button).](images/help/header-toolbar.svg)
+
+*The active zone is highlighted. Extra management buttons appear only in Edit mode.*
+
+| Mode | Purpose |
+|------|--------|
+| **Run mode** | Day-to-day control: choose a zone, tap presets, apply profiles. Management buttons are hidden. |
+| **Edit mode** | Full setup: zones, presets, patterns, colour palette, **Send Presets**, profile create/clone/delete, preset reordering, and per-tile **Edit** on the strip. |
+
+**Profiles** is available in both modes: in Run mode you can only **apply** a profile; in Edit mode you can also **create**, **clone**, and **delete** profiles.
+
+---
+
+## Zones
+
+- **Select a zone**: click its button in the top bar. The main area shows that zone’s preset strip and controls.
+- **Edit mode — open zone settings**: **right-click** a zone button to change its name, **device IDs** (comma-separated), and which presets appear on the zone. Device identifiers are matched to each device’s **name** when the app builds `select` messages for the driver.
+- **Zones modal** (Edit mode): create new zones from the header **Zones** button. New zones need a name and device ID list (defaults to `1` if you leave a simple placeholder).
+- **Brightness slider** (per zone): adjusts **global** brightness sent to devices (`b` in the driver message), with a short debounce so small drags do not flood the link.
+
+---
+
+## Presets on the zone strip
+
+- **Run and Edit mode**: click the **main part** of a preset tile to **select** that preset on all devices assigned to the current zone (same logical action as a `select` in the driver API).
+- **Edit mode only**:
+  - **Edit** beside a tile opens the preset editor for that preset, scoped to the current zone (so you can **Remove from zone** without deleting the preset from the profile).
+  - **Drag and drop** tiles to reorder them; order is saved for that zone.
+
+![Schematic: zone title, brightness slider, and a row of preset tiles; Edit mode adds an Edit control and drag handles for reordering.](images/help/zone-preset-strip.svg)
+
+*The slider controls global brightness for the zone’s devices. Click the coloured area of a tile to select that preset.*
+
+The **Presets** header button (Edit mode) opens a **profile-wide** list: **Add** new presets, **Edit**, **Send** (push definition over the transport), and **Delete** (removes the preset from the profile entirely).
+
+---
+
+## Preset editor
+
+- **Pattern**: chosen from the dropdown; optional **n1–n8** fields depend on the pattern (see **Pattern-specific parameters** in [API.md](API.md)).
+- **Colours**: choosing a value in the colour picker **adds** a swatch when the picker closes. Swatches can be **reordered** by dragging. Changing a swatch with the picker **clears** palette linkage for that slot.
+- **From Palette**: inserts a colour **linked** to the current profile’s palette. Linked slots show a **P** badge; if you change that palette entry later, presets using it update.
+- **Brightness (0–255)** and **Delay (ms)**: stored on the preset and sent with the compact preset payload.
+- **Try**: sends the current form values to devices on the **current zone**, then selects that preset — **without** `save` on the device (good for auditioning).
+- **Default**: updates the zone’s **default preset** and sends a **default** hint for those devices; it does not force the same live selection behaviour as clicking a tile.
+- **Save & Send**: writes the preset to the server, then pushes definitions with **save** so devices may persist them. It does **not** auto-select the preset on devices (use the strip or **Try** if you want that).
+- **Remove from zone** (when you opened the editor from a zone): removes the preset from **this zone’s list only**; the preset remains in the profile for other zones.
+
+![Schematic: preset editor with name, pattern, colour swatches (one with a P badge for palette-linked), and action buttons.](images/help/preset-editor.svg)
+
+*Try previews without persisting on the device; **Save & Send** stores the preset and pushes definitions with save.*
+
+---
+
+## Profiles
+
+- **Apply**: sets the **current profile** in your session. Zones and presets you see are scoped to that profile.
+- **Edit mode — Create**: new profiles always get a populated **default** zone. Optionally tick **DJ zone** to also create a `dj` zone (device name `dj`) with starter DJ-oriented presets.
+- **Clone** / **Delete**: available in Edit mode from the profile list.
+
+---
+
+## Send Presets (Edit mode)
+
+**Send Presets** walks **every zone** in the **current profile**, collects each zone’s preset IDs, and calls **`POST /presets/send`** per zone (including each zone’s **default** preset when set). Use this to bulk-push definitions to hardware after editing, without clicking **Send** on every preset individually.
+
+---
+
+## Patterns
+
+The **Patterns** dialog (Edit mode) lists pattern names and typical **delay** ranges from the pattern definitions. Choosing a pattern still happens inside the preset editor.
+
+**Wi-Fi drivers** can install new pattern modules over HTTP: the REST API exposes **`/patterns/ota/*`**, **`POST /patterns/<name>/send`**, **`POST /patterns/upload`**, and **`POST /patterns/driver`** (see [API.md](API.md)). ESP-NOW devices follow the bridge/serial path you configure for preset traffic.
+
+---
+
+## Colour palette
+
+**Colour Palette** (Edit mode) edits the **current profile’s** palette swatches. Those colours are reused by **From Palette** in the preset editor and stay in sync while the **P** link remains.
+
+![Schematic: palette modal with a row of swatches for the current profile.](images/help/colour-palette.svg)
+
+*Add or change swatches here; linked preset colours update automatically.*
+
+---
+
+## Mobile layout
+
+On narrow screens, use **Menu** to reach the same actions as the desktop header (Profiles, Zones, Presets, Help, mode toggle, etc.).
+
+![Schematic: narrow layout with Menu and the same header actions in a dropdown.](images/help/mobile-menu.svg)
+
+*Preset tiles behave the same once a zone is selected.*
+
+---
+
+## Further reading
+
+- **[API.md](API.md)** — REST routes, session scoping, WebSocket `/ws`, and LED driver JSON (`presets`, `select`, `save`, `default`, pattern keys, pattern **manifest**).
+- **README** — `pipenv run run`, port 80 setup, and high-level behaviour.

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>

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>

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>

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>

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>

docs/images/help/colour-palette.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 140" width="480" height="140">
+  <title>Colour Palette modal (concept)</title>
+  <rect width="480" height="140" fill="#2a2a2a" stroke="#555" stroke-width="1" rx="6"/>
+  <text x="20" y="28" fill="#fff" font-family="sans-serif" font-size="15" font-weight="600">Colour Palette</text>
+  <text x="20" y="48" fill="#888" font-family="sans-serif" font-size="10">Profile: current profile name</text>
+  <rect x="20" y="58" width="44" height="44" rx="4" fill="#e53935" stroke="#333"/>
+  <rect x="72" y="58" width="44" height="44" rx="4" fill="#fdd835" stroke="#333"/>
+  <rect x="124" y="58" width="44" height="44" rx="4" fill="#43a047" stroke="#333"/>
+  <rect x="176" y="58" width="44" height="44" rx="4" fill="#1e88e5" stroke="#333"/>
+  <rect x="228" y="58" width="44" height="44" rx="4" fill="#8e24aa" stroke="#333"/>
+  <rect x="280" y="70" width="36" height="28" rx="3" fill="#1a1a1a" stroke="#666"/>
+  <text x="288" y="88" fill="#ccc" font-family="sans-serif" font-size="10">+</text>
+  <text x="20" y="122" fill="#aaa" font-family="sans-serif" font-size="10">Swatches belong to the profile; preset editor uses them via From Palette.</text>
+</svg>

docs/images/help/header-toolbar.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 820 108" width="820" height="108">
+  <title>Header: tab buttons and action bar</title>
+  <rect width="820" height="108" fill="#1a1a1a"/>
+  <rect x="0" y="106" width="820" height="2" fill="#4a4a4a"/>
+  <text x="16" y="28" fill="#888" font-family="sans-serif" font-size="11">Tabs</text>
+  <rect x="16" y="40" width="72" height="36" rx="4" fill="#333" stroke="#666" stroke-width="1"/>
+  <text x="34" y="63" fill="#ccc" font-family="sans-serif" font-size="13">default</text>
+  <rect x="96" y="40" width="88" height="36" rx="4" fill="#2a4a7a" stroke="#5a8fd4" stroke-width="2"/>
+  <text x="108" y="63" fill="#fff" font-family="sans-serif" font-size="13">lounge</text>
+  <rect x="192" y="40" width="56" height="36" rx="4" fill="#333" stroke="#666" stroke-width="1"/>
+  <text x="204" y="63" fill="#ccc" font-family="sans-serif" font-size="13">dj</text>
+  <text x="380" y="28" fill="#888" font-family="sans-serif" font-size="11">Actions (Edit mode)</text>
+  <rect x="380" y="40" width="72" height="30" rx="3" fill="#3d3d3d" stroke="#555" stroke-width="1"/>
+  <text x="396" y="59" fill="#e0e0e0" font-family="sans-serif" font-size="11">Profiles</text>
+  <rect x="458" y="40" width="52" height="30" rx="3" fill="#3d3d3d" stroke="#555" stroke-width="1"/>
+  <text x="470" y="59" fill="#e0e0e0" font-family="sans-serif" font-size="11">Tabs</text>
+  <rect x="516" y="40" width="64" height="30" rx="3" fill="#3d3d3d" stroke="#555" stroke-width="1"/>
+  <text x="524" y="59" fill="#e0e0e0" font-family="sans-serif" font-size="11">Presets</text>
+  <rect x="586" y="40" width="78" height="30" rx="3" fill="#3d3d3d" stroke="#555" stroke-width="1"/>
+  <text x="598" y="59" fill="#e0e0e0" font-family="sans-serif" font-size="11">Patterns</text>
+  <rect x="670" y="40" width="134" height="30" rx="3" fill="#4a4a6a" stroke="#7a7aaf" stroke-width="1"/>
+  <text x="688" y="59" fill="#e0e0e0" font-family="sans-serif" font-size="11">Run mode</text>
+  <text x="16" y="98" fill="#aaa" font-family="sans-serif" font-size="10">Active tab highlighted. Mode button shows the mode you switch to next.</text>
+</svg>

docs/images/help/mobile-menu.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 300 340" width="300" height="340" role="img" aria-labelledby="t">
+  <title id="t">Narrow screen: Menu aggregates header actions</title>
+  <rect width="300" height="340" fill="#2e2e2e"/>
+  <rect x="0" y="0" width="300" height="52" fill="#1a1a1a"/>
+  <rect x="12" y="12" width="56" height="28" rx="4" fill="#3d3d3d" stroke="#555" stroke-width="1"/>
+  <text x="22" y="30" fill="#eee" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="12">Menu <20></text>
+  <rect x="76" y="14" width="52" height="24" rx="4" fill="#333" stroke="#666" stroke-width="1"/>
+  <text x="86" y="30" fill="#ccc" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="11">tab</text>
+  <rect x="136" y="14" width="52" height="24" rx="4" fill="#2a4a7a" stroke="#5a8fd4" stroke-width="1"/>
+  <text x="142" y="30" fill="#fff" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="11">tab</text>
+  <rect x="12" y="60" width="276" height="168" rx="4" fill="#252525" stroke="#4a4a4a" stroke-width="1"/>
+  <text x="24" y="84" fill="#888" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="10">Dropdown (same actions as desktop header)</text>
+  <g font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="12" fill="#e8e8e8">
+    <text x="24" y="108">Run mode</text>
+    <text x="24" y="132">Profiles</text>
+    <text x="24" y="156">Tabs</text>
+    <text x="24" y="180">Presets</text>
+    <text x="24" y="204">Help</text>
+  </g>
+  <rect x="12" y="240" width="276" height="80" rx="6" fill="#222" stroke="#444" stroke-width="1"/>
+  <text x="24" y="268" fill="#aaa" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="10">Content area  presets as on desktop</text>
+  <rect x="24" y="278" width="80" height="32" rx="4" fill="#333" stroke="#555"/>
+  <text x="36" y="298" fill="#ddd" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="11">preset</text>
+  <rect x="112" y="278" width="80" height="32" rx="4" fill="#333" stroke="#555"/>
+  <text x="124" y="298" fill="#ddd" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="11">preset</text>
+</svg>

docs/images/help/preset-editor.svg

@@ -0,0 +1,31 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 400" width="520" height="400">
+  <title>Preset editor modal (simplified)</title>
+  <rect width="520" height="400" fill="#1e1e1e"/>
+  <rect x="40" y="28" width="440" height="344" rx="8" fill="#2a2a2a" stroke="#555" stroke-width="1"/>
+  <text x="60" y="58" fill="#fff" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="17" font-weight="600">Preset</text>
+  <text x="60" y="86" fill="#aaa" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Name</text>
+  <rect x="60" y="92" width="200" height="28" rx="3" fill="#1a1a1a" stroke="#444" stroke-width="1"/>
+  <text x="72" y="111" fill="#ddd" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="12">evening glow</text>
+  <text x="280" y="86" fill="#aaa" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Pattern</text>
+  <rect x="280" y="92" width="160" height="28" rx="3" fill="#1a1a1a" stroke="#444" stroke-width="1"/>
+  <text x="292" y="111" fill="#ddd" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="12">pulse</text>
+  <text x="60" y="148" fill="#aaa" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Colours</text>
+  <rect x="60" y="156" width="48" height="48" rx="4" fill="#7e57c2" stroke="#333" stroke-width="1"/>
+  <circle cx="66" cy="162" r="8" fill="#3f51b5" stroke="#fff" stroke-width="1"/>
+  <text x="63" y="166" fill="#fff" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="7" font-weight="700">P</text>
+  <rect x="116" y="156" width="48" height="48" rx="4" fill="#26a69a" stroke="#333" stroke-width="1"/>
+  <text x="176" y="184" fill="#888" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="10">P = palette-linked</text>
+  <text x="60" y="232" fill="#aaa" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Brightness, delay, n1-n8</text>
+  <rect x="60" y="238" width="120" height="24" rx="3" fill="#1a1a1a" stroke="#444" stroke-width="1"/>
+  <text x="68" y="254" fill="#888" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">0-255</text>
+  <text x="60" y="290" fill="#aaa" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="10">Actions</text>
+  <rect x="60" y="298" width="44" height="26" rx="3" fill="#444" stroke="#666" stroke-width="1"/>
+  <text x="72" y="315" fill="#eee" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Try</text>
+  <rect x="112" y="298" width="56" height="26" rx="3" fill="#444" stroke="#666" stroke-width="1"/>
+  <text x="120" y="315" fill="#eee" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Default</text>
+  <rect x="176" y="298" width="88" height="26" rx="3" fill="#3d5a80" stroke="#5a7ab8" stroke-width="1"/>
+  <text x="188" y="315" fill="#fff" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Save+Send</text>
+  <rect x="272" y="298" width="48" height="26" rx="3" fill="#444" stroke="#666" stroke-width="1"/>
+  <text x="284" y="315" fill="#eee" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Close</text>
+  <text x="60" y="352" fill="#888" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="9">Try: preview without device save. Save+Send: store and push with save.</text>
+</svg>

docs/images/help/tab-preset-strip.svg

@@ -0,0 +1,35 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 220" width="800" height="220">
+  <title>Main area: brightness and preset tiles</title>
+  <defs>
+    <linearGradient id="rg1" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#ffd54f"/><stop offset="100%" style="stop-color:#fff8e1"/>
+    </linearGradient>
+    <linearGradient id="rg2" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#e53935"/><stop offset="33%" style="stop-color:#fdd835"/>
+      <stop offset="66%" style="stop-color:#43a047"/><stop offset="100%" style="stop-color:#1e88e5"/>
+    </linearGradient>
+    <linearGradient id="rg3" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#00897b"/><stop offset="100%" style="stop-color:#4db6ac"/>
+    </linearGradient>
+  </defs>
+  <rect width="800" height="220" fill="#2e2e2e"/>
+  <text x="20" y="32" fill="#fff" font-family="sans-serif" font-size="16" font-weight="600">lounge</text>
+  <text x="20" y="56" fill="#aaa" font-family="sans-serif" font-size="11">Brightness (global)</text>
+  <rect x="20" y="64" width="320" height="8" rx="4" fill="#444"/>
+  <rect x="20" y="64" width="200" height="8" rx="4" fill="#6a9ee2"/>
+  <circle cx="220" cy="68" r="10" fill="#ccc" stroke="#333" stroke-width="1"/>
+  <text x="360" y="74" fill="#888" font-family="sans-serif" font-size="11">drag to adjust</text>
+  <text x="20" y="108" fill="#aaa" font-family="sans-serif" font-size="11">Click tile body to select on tab devices</text>
+  <rect x="20" y="118" width="200" height="72" rx="6" fill="#252525" stroke="#555" stroke-width="1"/>
+  <rect x="28" y="128" width="184" height="36" rx="4" fill="url(#rg1)"/>
+  <text x="32" y="180" fill="#eee" font-family="sans-serif" font-size="13" font-weight="600">warm white</text>
+  <rect x="232" y="118" width="200" height="72" rx="6" fill="#252525" stroke="#6a9ee2" stroke-width="2"/>
+  <rect x="240" y="128" width="184" height="36" rx="4" fill="url(#rg2)"/>
+  <text x="244" y="180" fill="#eee" font-family="sans-serif" font-size="13" font-weight="600">rainbow</text>
+  <rect x="444" y="118" width="200" height="72" rx="6" fill="#252525" stroke="#555" stroke-width="1"/>
+  <rect x="452" y="128" width="184" height="36" rx="4" fill="url(#rg3)"/>
+  <text x="456" y="180" fill="#eee" font-family="sans-serif" font-size="13" font-weight="600">chase</text>
+  <rect x="656" y="130" width="56" height="48" rx="4" fill="#3d3d3d" stroke="#555" stroke-width="1"/>
+  <text x="670" y="158" fill="#ddd" font-family="sans-serif" font-size="11">Edit</text>
+  <text x="656" y="198" fill="#888" font-family="sans-serif" font-size="10">Edit mode: drag tiles to reorder</text>
+</svg>

docs/mockups/COLOR_PICKER_README.md

@@ -1,13 +1,13 @@
-# Custom Color Picker Component
+# Custom Colour Picker Component
 
-A cross-platform, cross-browser color picker component that provides a consistent user experience across all operating systems and browsers.
+A cross-platform, cross-browser colour picker component that provides a consistent user experience across all operating systems and browsers.
 
 ## Features
 
 ✅ **Consistent UI** - Same appearance and behavior on Windows, macOS, Linux, iOS, and Android  
 ✅ **Browser Support** - Works in Chrome, Firefox, Safari, Edge, Opera, and mobile browsers  
 ✅ **Touch Support** - Full touch/gesture support for mobile devices  
-✅ **HSB Color Model** - Uses Hue, Saturation, Brightness for intuitive color selection  
+✅ **HSB Colour Model** - Uses Hue, Saturation, Brightness for intuitive colour selection  
 ✅ **Multiple Input Methods** - Hex input, RGB inputs, and visual picker  
 ✅ **Accessible** - Keyboard accessible and screen reader friendly  
 ✅ **Customizable** - Easy to style and integrate  
@@ -33,7 +33,7 @@ A cross-platform, cross-browser color picker component that provides a consisten
 <div id="my-color-picker"></div>
 ```
 
-### 3. Initialize the color picker
+### 3. Initialize the colour picker
 
 ```javascript
 const picker = new ColorPicker('#my-color-picker', {
@@ -57,8 +57,8 @@ new ColorPicker(container, options)
 - `options` (object) - Configuration options
 
 **Options:**
-- `initialColor` (string) - Initial color in hex format (default: '#FF0000')
-- `onColorChange` (function) - Callback when color changes (receives hex color string)
+- `initialColor` (string) - Initial colour in hex format (default: '#FF0000')
+- `onColorChange` (function) - Callback when colour changes (receives hex colour string)
 - `showHexInput` (boolean) - Show hex input field (default: true)
 
 ### Methods
@@ -101,7 +101,7 @@ const picker = new ColorPicker('#picker1', {
 });
 ```
 
-### Multiple Color Pickers
+### Multiple Colour Pickers
 
 ```javascript
 const colors = ['#FF0000', '#00FF00', '#0000FF'];
@@ -116,7 +116,7 @@ const pickers = colors.map((color, index) => {
 });
 ```
 
-### Dynamic Color Picker Creation
+### Dynamic Colour Picker Creation
 
 ```javascript
 function addColorPicker(containerId, initialColor = '#000000') {
@@ -139,12 +139,12 @@ addColorPicker('color-2', '#00FF00');
 
 ## Styling
 
-The color picker uses CSS classes that can be customized:
+The colour picker uses CSS classes that can be customized:
 
 - `.color-picker-container` - Main container
-- `.color-picker-preview` - Color preview button
+- `.color-picker-preview` - Colour preview button
 - `.color-picker-panel` - Dropdown panel
-- `.color-picker-main` - Main color area
+- `.color-picker-main` - Main colour area
 - `.color-picker-hue` - Hue slider
 - `.color-picker-controls` - Controls section
 
@@ -183,20 +183,20 @@ The color picker uses CSS classes that can be customized:
 - ✅ iOS 12+
 - ✅ Android 7+
 
-## Color Format
+## Colour Format
 
-The color picker uses **hex color format** (`#RRGGBB`):
+The colour picker uses **hex colour format** (`#RRGGBB`):
 - Always returns uppercase hex strings (e.g., `#FF0000`)
 - Accepts both uppercase and lowercase input
 - Automatically validates hex format
 
 ## Integration with LED Driver Mockups
 
-The color picker is integrated into:
-- `dashboard.html` - Color selection for patterns
-- `presets.html` - Color selection when creating/editing presets
+The colour picker is integrated into:
+- `dashboard.html` - Colour selection for patterns
+- `presets.html` - Colour selection when creating/editing presets
 
-### Example: Getting Colors from Multiple Pickers
+### Example: Getting Colours from Multiple Pickers
 
 ```javascript
 const colorPickers = [];
@@ -218,7 +218,7 @@ function sendColorsToDevice() {
 ## Performance
 
 - Lightweight: ~14KB JavaScript, ~4KB CSS
-- Fast rendering: Uses Canvas API for color gradients
+- Fast rendering: Uses Canvas API for colour gradients
 - Smooth interactions: Optimized event handling
 - Memory efficient: No external dependencies
 
@@ -235,5 +235,5 @@ Part of the LED Driver project. Use freely in your projects.
 
 ## Demo
 
-See `color-picker-demo.html` for a live demonstration of the color picker component.
+See `color-picker-demo.html` for a live demonstration of the colour picker component.