chore(submodules): bump led-driver

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

.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/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

@@ -1,5 +1,7 @@
 # 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
@@ -23,8 +25,22 @@ ENV/
 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

@@ -4,3 +4,6 @@
 [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,6 +6,7 @@ name = "pypi"
 [packages]
 mpremote = "*"
 pyserial = "*"
+pyserial-asyncio = "*"
 esptool = "*"
 pyjwt = "*"
 watchfiles = "*"
@@ -13,17 +14,21 @@ 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 tests/web.py' src tests"
-install = "pipenv install"
+web = "python tests/web.py"
+watch = "python -m watchfiles \"python tests/web.py\" src tests"
 run = "sh -c 'cd src && python main.py'"
-dev = "watchfiles \"sh -c 'cd src && python main.py'\" src"
-help-pdf = "sh scripts/build_help_pdf.sh"
+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,23 +1,28 @@
 # led-controller
 
-LED controller web app for managing profiles, tabs, presets, and colour palettes, and sending commands to LED devices over the serial -> ESP-NOW bridge.
+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`
+- 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 tabs/presets and apply profiles. Editing actions are hidden.
-- **Edit mode**: management view. Shows Tabs, Presets, Patterns, Colour Palette, and Send Presets controls, plus per-tile preset edit/remove and drag-reorder.
+- **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 behavior (no create/clone/delete).
+- 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:
@@ -35,3 +40,6 @@ LED controller web app for managing profiles, tabs, presets, and colour palettes
 
 - 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))

db/device.json

@@ -1 +0,0 @@
-{"f0f5bdfb9d30": {"id": "f0f5bdfb9d30", "name": "a", "type": "led", "transport": "wifi", "address": "10.1.1.182", "default_pattern": null, "zones": []}, "188b0e1560a8": {"id": "188b0e1560a8", "name": "a", "type": "led", "transport": "wifi", "address": "10.1.1.242", "default_pattern": null, "zones": []}, "24ec4acaffcc": {"id": "24ec4acaffcc", "name": "c", "type": "led", "transport": "wifi", "address": "10.1.1.171", "default_pattern": null, "zones": []}}

db/palette.json

@@ -1 +1 @@
-{"1": ["#FF0000", "#00FF00", "#0000FF", "#FFFF00", "#FF00FF", "#00FFFF", "#FFFFFF", "#000000"], "2": [], "3": [], "4": [], "5": [], "6": [], "7": ["#FF0000", "#00FF00", "#0000FF", "#FFFF00", "#FF00FF", "#00FFFF", "#FFFFFF", "#000000"], "8": [], "9": [], "10": [], "11": [], "12": ["#890b0b", "#0b8935"]}
+{"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", "type": "zones", "zones": ["1", "8"], "scenes": [], "palette_id": "1"}, "2": {"name": "test", "type": "zones", "zones": ["6", "7"], "scenes": [], "palette_id": "12"}}
+{"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/zone.json

@@ -1 +0,0 @@
-{"1": {"name": "default", "names": ["a", "c", "a"], "presets": [["4", "2", "7"], ["3", "14", "5"], ["8", "10", "11"], ["9", "12", "1"], ["13", "37", "6"]], "presets_flat": ["4", "2", "7", "3", "14", "5", "8", "10", "11", "9", "12", "1", "13", "37", "6"], "default_preset": "15"}, "2": {"name": "default", "names": ["1", "2", "3", "4", "5", "6", "7", "8", "0", "a"], "presets": [["16", "17", "18"], ["19", "20", "21"], ["22", "23", "24"], ["25", "26", "27"], ["28", "29", "30"]], "presets_flat": ["16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30"]}, "3": {"name": "default", "names": ["1"], "presets": [], "default_preset": null}, "4": {"name": "default", "names": ["1"], "presets": [], "default_preset": null}, "5": {"name": "dj", "names": ["dj"], "presets": [["31", "32", "33"]], "default_preset": "31", "presets_flat": ["31", "32", "33"]}, "6": {"name": "default", "names": ["1"], "presets": [], "default_preset": null}, "7": {"name": "dj", "names": ["dj"], "presets": [["34", "35", "36"]], "default_preset": "34", "presets_flat": ["34", "35", "36"]}, "8": {"name": "test", "names": ["11"], "presets": [["1", "2", "3"], ["4", "5"]], "default_preset": "1", "presets_flat": ["1", "2", "3", "4", "5"]}}

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

@@ -2,10 +2,12 @@
 
 This document covers:
 
-1. **HTTP and WebSocket** exposed by the Raspberry Pi app (`src/main.py`) — profiles, presets, transport send, and related resources.
-2. **LED driver JSON** — the compact message format sent over the serial→ESP-NOW bridge to devices (same logical API as ESP-NOW payloads).
+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).
 
-Default listen address: `0.0.0.0`. Port defaults to **80**; override with the `PORT` environment variable (see `pipenv run run`).
+Default HTTP listen address: `0.0.0.0`. Port defaults to **80**; override with the **`PORT`** environment variable (see `pipenv run run`).
+
+**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.
 
@@ -16,7 +18,7 @@ All JSON APIs use `Content-Type: application/json` for bodies and responses unle
 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 (tabs, presets, patterns, colour palette, send presets, profile management actions, **Devices** registry for LED driver names/MACs, and related tools).
+- **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:
 
@@ -40,7 +42,7 @@ Profiles are selected with **`POST /profiles/<id>/apply`**, which sets `current_
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/` | Main UI (`templates/index.html`) |
-| GET | `/settings` | Settings page (`templates/settings.html`) |
+| GET | `/settings/page` | Standalone settings page (`templates/settings.html`) |
 | GET | `/favicon.ico` | Empty response (204) |
 | GET | `/static/<path>` | Static files under `src/static/` |
 
@@ -50,10 +52,12 @@ Profiles are selected with **`POST /profiles/<id>/apply`**, which sets `current_
 
 Connect to **`ws://<host>:<port>/ws`**.
 
-- Send **JSON**: the object is forwarded to the transport (serial bridge → ESP-NOW) as JSON. 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 is used.
+- Send **JSON**: the object is forwarded through the **ESP-NOW bridge** (devices envelope or legacy MAC-prefixed payload). Optional key **`to`**: 12-character hex MAC address; if present it is removed from the object and the payload is sent to that peer; otherwise the default destination from settings is used.
 - Send **non-JSON text**: forwarded as raw bytes with the default address.
 - On send failure, the server may reply with `{"error": "Send failed"}`.
 
+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
@@ -68,7 +72,7 @@ Below, `<id>` values are string identifiers used by the JSON stores (numeric str
 | 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` (same page as `GET /settings` from the root app, for convenience). |
+| GET | `/settings/page` | Serves `templates/settings.html`. |
 
 ### Devices — `/devices`
 
@@ -77,11 +81,11 @@ Registry in `db/device.json`: storage key **`<id>`** (string, e.g. `"1"`) maps t
 | Field | Description |
 |-------|-------------|
 | **`id`** | Same as the storage key (stable handle for URLs). |
-| **`name`** | Shown in tabs and used in `select` keys. |
+| **`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`**, **`tabs`** | Optional, as before. |
+| **`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).
 
@@ -89,7 +93,7 @@ Existing records without `type` / `transport` / `id` are backfilled on load (`le
 |--------|------|-------------|
 | 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`**, **`tabs`**. Returns `{ "<id>": { ... } }`, 201. |
+| 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. |
 
@@ -102,7 +106,7 @@ Existing records without `type` / `transport` / `id` are backfilled on load (`le
 | 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 (tabs, palettes, presets). Body may include `name`. |
+| 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. |
@@ -143,11 +147,11 @@ 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.
 
-### Tabs — `/zones`
+### Zones — `/zones`
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/zones` | `tabs`, `zone_order`, `current_zone_id`, `profile_id` for the session-backed profile. |
+| 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. |
@@ -198,20 +202,33 @@ Stored preset records can include:
 
 ### 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/definitions` | Contents of `pattern.json` (pattern metadata for the UI). |
-| GET | `/patterns` | All pattern records. |
-| GET | `/patterns/<id>` | One pattern. |
+| 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)
+## 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.
+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
 

docs/SPECIFICATION.md

@@ -350,7 +350,7 @@ Manage connected devices and create/manage device groups.
 
 #### Layout
 - **Header:** Title with "Add Device" button
-- **Tabs:** Devices and Groups tabs
+- **Zones:** Devices and Groups zones (zone buttons / zone strip)
 - **Content Area:** Zone-specific content
 
 #### Devices Zone
@@ -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

@@ -1,6 +1,6 @@
 # LED controller — user guide
 
-This page describes the **main web UI** served from the Raspberry Pi app: profiles, tabs, presets, colour palettes, and sending commands to LED devices over the serial → ESP-NOW bridge.
+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**.
 
@@ -12,24 +12,24 @@ Figures below are **schematic** (layout and ideas), not pixel-perfect screenshot
 
 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, Tabs, Presets, Patterns, and the mode toggle on the right (example shows Edit mode with “Run mode” on the button).](images/help/header-toolbar.svg)
+![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: tabs, presets, patterns, colour palette, **Send Presets**, profile create/clone/delete, preset reordering, and per-tile **Edit** on the strip. |
+| **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.
 
 ---
 
-## Tabs
+## 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.
-- **Tabs modal** (Edit mode): create new tabs from the header **Tabs** button. New tabs need a name and device ID list (defaults to `1` if you leave a simple placeholder).
+- **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.
 
 ---
@@ -68,7 +68,7 @@ The **Presets** header button (Edit mode) opens a **profile-wide** list: **Add**
 
 ## Profiles
 
-- **Apply**: sets the **current profile** in your session. Tabs and presets you see are scoped to that profile.
+- **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.
 
@@ -82,7 +82,9 @@ The **Presets** header button (Edit mode) opens a **profile-wide** list: **Add**
 
 ## Patterns
 
-The **Patterns** dialog (Edit mode) is a **read-only reference**: pattern names and typical **delay** ranges from the pattern definitions. It does not change device behaviour by itself; patterns are chosen inside the preset editor.
+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.
 
 ---
 
@@ -98,7 +100,7 @@ The **Patterns** dialog (Edit mode) is a **read-only reference**: pattern names
 
 ## Mobile layout
 
-On narrow screens, use **Menu** to reach the same actions as the desktop header (Profiles, Tabs, Presets, Help, mode toggle, etc.).
+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)
 
@@ -108,5 +110,5 @@ On narrow screens, use **Menu** to reach the same actions as the desktop header
 
 ## Further reading
 
-- **[API.md](API.md)** — REST routes, session scoping, WebSocket `/ws`, and LED driver JSON (`presets`, `select`, `save`, `default`, pattern keys).
+- **[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>

esp32/benchmark_peers.py

@@ -1,112 +0,0 @@
-# Benchmark: LRU eviction vs add-then-remove-after-use on ESP32.
-# Run on device: mpremote run esp32/benchmark_peers.py
-# (add/del_peer are timed; send() may fail if no peer is listening - timing still valid)
-import espnow
-import network
-import time
-
-BROADCAST = b"\xff\xff\xff\xff\xff\xff"
-MAX_PEERS = 20
-ITERATIONS = 50
-PAYLOAD = b"x" * 32  # small payload
-
-network.WLAN(network.STA_IF).active(True)
-esp = espnow.ESPNow()
-esp.active(True)
-esp.add_peer(BROADCAST)
-
-# Build 19 dummy MACs so we have 20 peers total (broadcast + 19).
-def mac(i):
-    return bytes([0, 0, 0, 0, 0, i])
-peers_list = [mac(i) for i in range(1, 20)]
-for p in peers_list:
-    esp.add_peer(p)
-
-# One "new" MAC we'll add/remove.
-new_mac = bytes([0, 0, 0, 0, 0, 99])
-
-def bench_lru():
-    """LRU: ensure_peer (evict oldest + add new), send, update last_used."""
-    last_used = {BROADCAST: time.ticks_ms()}
-    for p in peers_list:
-        last_used[p] = time.ticks_ms()
-    # Pre-remove one so we have 19; ensure_peer(new) will add 20th.
-    esp.del_peer(peers_list[-1])
-    last_used.pop(peers_list[-1], None)
-    # Now 19 peers. Each iteration: ensure_peer(new) -> add_peer(new), send, update.
-    # Next iter: ensure_peer(new) -> already there, just send. So we need to force
-    # eviction each time: use a different "new" each time so we always evict+add.
-    t0 = time.ticks_us()
-    for i in range(ITERATIONS):
-        addr = bytes([0, 0, 0, 0, 0, 50 + (i % 30)])  # 30 different "new" MACs
-        peers = esp.get_peers()
-        peer_macs = [p[0] for p in peers]
-        if addr not in peer_macs:
-            if len(peer_macs) >= MAX_PEERS:
-                oldest_mac = None
-                oldest_ts = time.ticks_ms()
-                for m in peer_macs:
-                    if m == BROADCAST:
-                        continue
-                    ts = last_used.get(m, 0)
-                    if ts <= oldest_ts:
-                        oldest_ts = ts
-                        oldest_mac = m
-                if oldest_mac is not None:
-                    esp.del_peer(oldest_mac)
-                    last_used.pop(oldest_mac, None)
-            esp.add_peer(addr)
-        esp.send(addr, PAYLOAD)
-        last_used[addr] = time.ticks_ms()
-    t1 = time.ticks_us()
-    return time.ticks_diff(t1, t0)
-
-def bench_add_then_remove():
-    """Add peer, send, del_peer (remove after use). At 20 we must del one first."""
-    # Start full: 20 peers. To add new we del any one, add new, send, del new.
-    victim = peers_list[0]
-    t0 = time.ticks_us()
-    for i in range(ITERATIONS):
-        esp.del_peer(victim)  # make room
-        esp.add_peer(new_mac)
-        esp.send(new_mac, PAYLOAD)
-        esp.del_peer(new_mac)
-        esp.add_peer(victim)  # put victim back so we're at 20 again
-    t1 = time.ticks_us()
-    return time.ticks_diff(t1, t0)
-
-def bench_send_existing():
-    """Baseline: send to existing peer only (no add/del)."""
-    t0 = time.ticks_us()
-    for _ in range(ITERATIONS):
-        esp.send(peers_list[0], PAYLOAD)
-    t1 = time.ticks_us()
-    return time.ticks_diff(t1, t0)
-
-print("ESP-NOW peer benchmark ({} iterations)".format(ITERATIONS))
-print()
-
-# Baseline: send to existing peer
-try:
-    us = bench_send_existing()
-    print("Send to existing peer only: {:>8} us total  {:>7.1f} us/iter".format(us, us / ITERATIONS))
-except Exception as e:
-    print("Send existing failed:", e)
-print()
-
-# LRU: evict oldest then add new, send
-try:
-    us = bench_lru()
-    print("LRU (evict oldest + add + send): {:>8} us total  {:>7.1f} us/iter".format(us, us / ITERATIONS))
-except Exception as e:
-    print("LRU failed:", e)
-print()
-
-# Add then remove after use
-try:
-    us = bench_add_then_remove()
-    print("Add then remove after use:       {:>8} us total  {:>7.1f} us/iter".format(us, us / ITERATIONS))
-except Exception as e:
-    print("Add-then-remove failed:", e)
-print()
-print("Done.")

esp32/main.py

@@ -1,253 +0,0 @@
-# Serial-to-ESP-NOW bridge: JSON in both directions on UART + ESP-NOW.
-#
-# Pi → UART (two supported forms):
-#   A) Legacy: 6 bytes destination MAC + UTF-8 JSON payload (one write = one frame).
-#   B) Newline JSON: one object per line, UTF-8, ending with \n
-#      - Multicast via ESP32: {"m":"split","peers":["12hex",...],"body":{...}}
-#      - Unicast / broadcast: {"to":"12hex","v":"1",...}  (all keys except to/dest go to peers)
-#
-# ESP-NOW → Pi: newline-delimited JSON, one object per packet:
-#   {"dir":"espnow_rx","from":"<12hex>","payload":{...}}   if body was JSON
-#   {"dir":"espnow_rx","from":"<12hex>","payload_text":"..."} if UTF-8 not JSON
-#   {"dir":"espnow_rx","from":"<12hex>","payload_b64":"..."} if binary
-from machine import Pin, UART
-import espnow
-import json
-import network
-import time
-import ubinascii
-
-UART_BAUD = 912000
-BROADCAST = b"\xff\xff\xff\xff\xff\xff"
-MAX_PEERS = 20
-WIFI_CHANNEL = 6
-
-sta = network.WLAN(network.STA_IF)
-sta.active(True)
-sta.config(pm=network.WLAN.PM_NONE, channel=WIFI_CHANNEL)
-print("WiFi STA channel:", sta.config("channel"), "(WIFI_CHANNEL=%s)" % WIFI_CHANNEL)
-
-esp = espnow.ESPNow()
-esp.active(True)
-esp.add_peer(BROADCAST)
-
-uart = UART(1, UART_BAUD, tx=Pin(21), rx=Pin(6))
-
-last_used = {BROADCAST: time.ticks_ms()}
-uart_rx_buf = b""
-
-ESP_ERR_ESPNOW_EXIST = -12395
-
-
-def ensure_peer(addr):
-    peers = esp.get_peers()
-    peer_macs = [p[0] for p in peers]
-    if addr in peer_macs:
-        return
-    if len(peer_macs) >= MAX_PEERS:
-        oldest_mac = None
-        oldest_ts = time.ticks_ms()
-        for mac in peer_macs:
-            if mac == BROADCAST:
-                continue
-            ts = last_used.get(mac, 0)
-            if ts <= oldest_ts:
-                oldest_ts = ts
-                oldest_mac = mac
-        if oldest_mac is not None:
-            esp.del_peer(oldest_mac)
-            last_used.pop(oldest_mac, None)
-    try:
-        esp.add_peer(addr)
-    except OSError as e:
-        if e.args[0] != ESP_ERR_ESPNOW_EXIST:
-            raise
-
-
-def try_apply_bridge_config(obj):
-    """Pi sends {"m":"bridge","ch":1..11} — set STA channel only; do not ESP-NOW forward."""
-    if not isinstance(obj, dict) or obj.get("m") != "bridge":
-        return False
-    ch = obj.get("ch")
-    if ch is None:
-        ch = obj.get("wifi_channel")
-    if ch is None:
-        return True
-    try:
-        n = int(ch)
-        if 1 <= n <= 11:
-            sta.config(pm=network.WLAN.PM_NONE, channel=n)
-            print("Bridge STA channel ->", n)
-    except Exception as e:
-        print("bridge config:", e)
-    return True
-
-
-def send_split_from_obj(obj):
-    """obj has m=split, peers=[12hex,...], body=dict."""
-    body = obj.get("body")
-    if body is None:
-        return
-    try:
-        out = json.dumps(body).encode("utf-8")
-    except (TypeError, ValueError):
-        return
-    for peer in obj.get("peers") or []:
-        if not isinstance(peer, str) or len(peer) != 12:
-            continue
-        try:
-            mac = bytes.fromhex(peer)
-        except ValueError:
-            continue
-        if len(mac) != 6:
-            continue
-        ensure_peer(mac)
-        esp.send(mac, out)
-        last_used[mac] = time.ticks_ms()
-
-
-def process_broadcast_payload_split_or_flood(payload):
-    try:
-        text = payload.decode("utf-8")
-        obj = json.loads(text)
-    except Exception:
-        obj = None
-    if isinstance(obj, dict) and try_apply_bridge_config(obj):
-        return
-    if (
-        isinstance(obj, dict)
-        and obj.get("m") == "split"
-        and isinstance(obj.get("peers"), list)
-    ):
-        send_split_from_obj(obj)
-        return
-    ensure_peer(BROADCAST)
-    esp.send(BROADCAST, payload)
-    last_used[BROADCAST] = time.ticks_ms()
-
-
-def process_legacy_uart_frame(data):
-    if not data or len(data) < 6:
-        return
-    addr = data[:6]
-    payload = data[6:]
-    if addr == BROADCAST:
-        process_broadcast_payload_split_or_flood(payload)
-        return
-    ensure_peer(addr)
-    esp.send(addr, payload)
-    last_used[addr] = time.ticks_ms()
-
-
-def handle_json_command_line(obj):
-    if not isinstance(obj, dict):
-        return
-    if try_apply_bridge_config(obj):
-        return
-    if obj.get("m") == "split" and isinstance(obj.get("peers"), list):
-        send_split_from_obj(obj)
-        return
-    to = obj.get("to") or obj.get("dest")
-    if isinstance(to, str) and len(to) == 12:
-        try:
-            mac = bytes.fromhex(to)
-        except ValueError:
-            return
-        if len(mac) != 6:
-            return
-        body = {k: v for k, v in obj.items() if k not in ("to", "dest")}
-        if not body:
-            return
-        try:
-            out = json.dumps(body).encode("utf-8")
-        except (TypeError, ValueError):
-            return
-        ensure_peer(mac)
-        esp.send(mac, out)
-        last_used[mac] = time.ticks_ms()
-
-
-def drain_uart_json_lines():
-    """Parse leading newline-delimited JSON objects from uart_rx_buf; leave rest."""
-    global uart_rx_buf
-    while True:
-        s = uart_rx_buf.lstrip()
-        if not s:
-            uart_rx_buf = b""
-            return
-        if s[0] != ord("{"):
-            uart_rx_buf = s
-            return
-        nl = s.find(b"\n")
-        if nl < 0:
-            uart_rx_buf = s
-            return
-        line = s[:nl].strip()
-        uart_rx_buf = s[nl + 1 :]
-        if line:
-            try:
-                text = line.decode("utf-8")
-                obj = json.loads(text)
-                handle_json_command_line(obj)
-            except Exception as e:
-                print("UART JSON line error:", e)
-        # continue; there may be another JSON line in buffer
-
-
-def drain_uart_legacy_frame():
-    """If buffer does not start with '{', treat whole buffer as one 6-byte MAC + JSON frame."""
-    global uart_rx_buf
-    s = uart_rx_buf
-    if not s or s[0] == ord("{"):
-        return
-    if len(s) < 6:
-        return
-    data = s
-    uart_rx_buf = b""
-    process_legacy_uart_frame(data)
-
-
-def forward_espnow_to_uart(mac, msg):
-    peer_hex = ubinascii.hexlify(mac).decode()
-    try:
-        text = msg.decode("utf-8")
-        try:
-            payload = json.loads(text)
-            line_obj = {"dir": "espnow_rx", "from": peer_hex, "payload": payload}
-        except ValueError:
-            line_obj = {"dir": "espnow_rx", "from": peer_hex, "payload_text": text}
-    except UnicodeDecodeError:
-        line_obj = {
-            "dir": "espnow_rx",
-            "from": peer_hex,
-            "payload_b64": ubinascii.b64encode(msg).decode(),
-        }
-    try:
-        line = json.dumps(line_obj) + "\n"
-        uart.write(line.encode("utf-8"))
-    except Exception as e:
-        print("UART TX error:", e)
-
-
-print("Starting ESP32 bridge (UART JSON + legacy MAC+JSON, ESP-NOW RX → UART JSON lines)")
-
-while True:
-    idle = True
-    if uart.any():
-        idle = False
-        uart_rx_buf += uart.read()
-        drain_uart_json_lines()
-        drain_uart_legacy_frame()
-
-    try:
-        peer, msg = esp.recv(0)
-    except OSError:
-        peer, msg = None, None
-
-    if peer is not None and msg is not None:
-        idle = False
-        if len(peer) == 6:
-            forward_espnow_to_uart(peer, msg)
-
-    if idle:
-        time.sleep_ms(1)

esp32/msg.json

@@ -1,21 +0,0 @@
-{
-    "ch": 6,
-    
-    "peers": {
-        "12:3456789012":{ 
-            "select": [["name1", "preset1"]]
-
-        ,
-        "ff:ff:ff:ff:ff:ff": {
-            "presets": {
-                "preset1": {
-                    "pattern": "on",
-                    "colors": ["#FF0000", "#00FF00", "#0000FF"],
-                    "delay": 100,
-                    "brightness": 127,
-                    "auto": true
-                }
-            }
-        }
-        }
-}

espnow-sender/src/bridge_http.py

@@ -0,0 +1,91 @@
+"""HTTP settings API for the ESP-NOW bridge (AP IP, password, channel)."""
+
+import json
+
+from settings import WIFI_CHANNEL_DEFAULT
+
+_SETTINGS_KEYS = frozenset(
+    {"name", "ap_ip", "ap_password", "wifi_channel", "ws_port", "max_peers"}
+)
+
+
+def _parse_ipv4(value):
+    parts = str(value).strip().split(".")
+    if len(parts) != 4:
+        raise ValueError("ap_ip must be dotted IPv4")
+    out = []
+    for p in parts:
+        n = int(p)
+        if n < 0 or n > 255:
+            raise ValueError("ap_ip octet out of range")
+        out.append(n)
+    return ".".join(str(x) for x in out)
+
+
+def public_settings(settings):
+    return {
+        "name": settings.get("name", ""),
+        "ap_ip": settings.get("ap_ip", "192.168.4.1"),
+        "ap_password_set": bool(str(settings.get("ap_password") or "").strip()),
+        "wifi_channel": settings.get("wifi_channel", WIFI_CHANNEL_DEFAULT),
+        "ws_port": settings.get("ws_port", 80),
+        "max_peers": settings.get("max_peers", 20),
+    }
+
+
+def apply_settings_update(settings, data):
+    if not isinstance(data, dict):
+        raise ValueError("body must be a JSON object")
+    reboot_required = False
+    if "name" in data:
+        name = str(data["name"] or "").strip()
+        if not name:
+            raise ValueError("name is required")
+        if len(name) > 32:
+            raise ValueError("name too long")
+        settings["name"] = name
+        reboot_required = True
+    if "ap_ip" in data:
+        settings["ap_ip"] = _parse_ipv4(data["ap_ip"])
+        reboot_required = True
+    if "ap_password" in data:
+        pw = str(data["ap_password"] or "")
+        if pw and len(pw) < 8:
+            raise ValueError("ap_password must be at least 8 characters or empty")
+        settings["ap_password"] = pw
+        reboot_required = True
+    if "wifi_channel" in data:
+        ch = int(data["wifi_channel"])
+        if ch < 1 or ch > 11:
+            raise ValueError("wifi_channel must be 1–11")
+        settings["wifi_channel"] = ch
+        reboot_required = True
+    if "ws_port" in data:
+        port = int(data["ws_port"])
+        if port < 1 or port > 65535:
+            raise ValueError("ws_port out of range")
+        settings["ws_port"] = port
+    if "max_peers" in data:
+        settings["max_peers"] = max(1, min(20, int(data["max_peers"])))
+    return reboot_required
+
+
+def register_bridge_routes(app, settings):
+    @app.get("/settings")
+    async def get_bridge_settings(request):
+        return json.dumps(public_settings(settings)), 200, {"Content-Type": "application/json"}
+
+    @app.put("/settings")
+    async def put_bridge_settings(request):
+        try:
+            data = request.json
+            reboot_required = apply_settings_update(settings, data)
+            settings.save()
+            body = public_settings(settings)
+            body["message"] = "Settings saved"
+            body["reboot_required"] = reboot_required
+            return json.dumps(body), 200, {"Content-Type": "application/json"}
+        except ValueError as err:
+            return json.dumps({"error": str(err)}), 400, {"Content-Type": "application/json"}
+        except Exception as err:
+            return json.dumps({"error": str(err)}), 500, {"Content-Type": "application/json"}

espnow-sender/src/main.py

@@ -0,0 +1,133 @@
+import asyncio
+import json
+
+from microdot import Microdot
+from microdot.websocket import WebSocketError, with_websocket
+
+import aioespnow
+import machine
+from settings import Settings
+from espnow_wire import BROADCAST_MAC, pack_ws_uplink
+from peer_table import PeerTable, load_max_peers
+from downlink_router import is_devices_envelope, route_envelope
+from wifi_ap import init_bridge_network
+from util import print_bridge_ip
+from bridge_http import register_bridge_routes
+from machine import UART, Pin
+
+wdt = machine.WDT(timeout=10000)
+wdt.feed()
+machine.freq(160000000)
+settings = Settings()
+print(settings)
+
+uart = UART(1, baudrate=921600, tx=Pin(2), rx=Pin(3))
+
+app = Microdot()
+register_bridge_routes(app, settings)
+
+init_bridge_network(settings)
+print_bridge_ip(settings.get("ws_port", 80))
+
+esp = aioespnow.AIOESPNow()
+esp.active(True)
+esp.add_peer(BROADCAST_MAC)
+
+peer_table = PeerTable(load_max_peers())
+clients = set()
+
+
+def _note_uplink_peer(host, msg):
+    if host and len(host) == 6:
+        name = None
+        if msg and msg[0:1] == b"{":
+            try:
+                data = json.loads(msg)
+                if isinstance(data, dict):
+                    name = data.get("name")
+            except (ValueError, TypeError):
+                pass
+        peer_table.touch(host, name, esp)
+
+
+@app.route("/ws")
+@with_websocket
+async def ws(request, ws):
+    clients.add(ws)
+    try:
+        while True:
+            try:
+                raw = await ws.receive()
+            except WebSocketError as err:
+                print(err)
+                break
+            if not raw:
+                break
+            if isinstance(raw, str):
+                raw = raw.encode("utf-8")
+            try:
+                if is_devices_envelope(raw):
+                    await route_envelope(esp, peer_table, raw)
+                else:
+                    await esp.asend(BROADCAST_MAC, raw)
+                print(raw)
+                print("ws tx", len(raw), "B")
+            except Exception as err:
+                print(err)
+                break
+    finally:
+        clients.discard(ws)
+
+
+async def _espnow_receive_loop():
+    async for host, msg in esp:
+        if not host or not msg:
+            continue
+        _note_uplink_peer(host, msg)
+        print("espnow rx", len(msg), "B")
+        frame = pack_ws_uplink(host, msg)
+        dead = []
+        for client in list(clients):
+            try:
+                await client.send(frame)
+            except Exception:
+                dead.append(client)
+        for client in dead:
+            clients.discard(client)
+        uart.write(msg)
+
+
+async def _serial_receive_loop():
+    while True:
+        if uart.any():
+            raw = uart.read()
+            print(raw)
+            try:
+                if is_devices_envelope(raw):
+                    await route_envelope(esp, peer_table, raw)
+                else:
+                    await esp.asend(BROADCAST_MAC, raw)
+                print(raw)
+                print("ws tx", len(raw), "B")
+            except Exception as err:
+                print(err)
+                break
+           
+        await asyncio.sleep(0)
+
+
+async def _wdt_feed_loop():
+    while True:
+        await asyncio.sleep(1)
+        wdt.feed()
+
+
+async def main():
+    asyncio.create_task(_wdt_feed_loop())
+    asyncio.create_task(_espnow_receive_loop())
+    asyncio.create_task(_serial_receive_loop())
+    await app.start_server(host="0.0.0.0", port=80)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

espnow-sender/src/peer_table.py

@@ -0,0 +1,90 @@
+"""LRU table of ESP-NOW peer MACs seen on uplink."""
+
+from espnow_wire import BROADCAST_MAC
+
+try:
+    from settings import Settings
+except ImportError:
+    Settings = None
+
+# ESP32 counts the broadcast peer toward the ~20 peer limit.
+_RESERVED_FOR_BROADCAST = 1
+
+
+class PeerTable:
+    def __init__(self, max_peers=20):
+        limit = max(1, int(max_peers) - _RESERVED_FOR_BROADCAST)
+        self._max = limit
+        self._order = []
+        self._names = {}
+
+    def _evict_lru(self, esp):
+        if not self._order:
+            return
+        old = self._order.pop(0)
+        self._names.pop(old, None)
+        if esp is not None:
+            try:
+                esp.del_peer(old)
+            except OSError:
+                pass
+
+    def touch(self, mac_bytes, name=None, esp=None):
+        """Note a peer from uplink (LRU). Pass ``esp`` so evictions free ESP-NOW slots."""
+        if not mac_bytes or len(mac_bytes) != 6:
+            return
+        if mac_bytes == BROADCAST_MAC:
+            return
+        if mac_bytes in self._order:
+            self._order.remove(mac_bytes)
+        elif len(self._order) >= self._max:
+            self._evict_lru(esp)
+        self._order.append(mac_bytes)
+        if name:
+            self._names[mac_bytes] = str(name)
+        if esp is not None:
+            try:
+                esp.add_peer(mac_bytes)
+            except OSError:
+                pass
+
+    def ensure_peer(self, esp, mac_bytes):
+        """Register ``mac_bytes`` on ESP-NOW, evicting LRU peers when the table is full."""
+        if not mac_bytes or len(mac_bytes) != 6:
+            return False
+        if mac_bytes == BROADCAST_MAC:
+            try:
+                esp.add_peer(mac_bytes)
+            except OSError:
+                pass
+            return True
+        if mac_bytes in self._order:
+            self._order.remove(mac_bytes)
+            self._order.append(mac_bytes)
+        else:
+            while len(self._order) >= self._max:
+                self._evict_lru(esp)
+            self._order.append(mac_bytes)
+        # Uplink touch() only updates LRU; always add_peer before unicast send.
+        try:
+            esp.add_peer(mac_bytes)
+        except OSError as err:
+            print("add_peer failed", err)
+            return False
+        return True
+
+    def peers(self):
+        return list(self._order)
+
+    def is_broadcast_mac(self, mac_bytes):
+        return mac_bytes == BROADCAST_MAC
+
+
+def load_max_peers():
+    if Settings is None:
+        return 20
+    try:
+        s = Settings()
+        return int(s.get("max_peers", 20))
+    except Exception:
+        return 20

espnow-sender/src/util.py

@@ -0,0 +1,48 @@
+def parse_mac(value):
+    raw = value.strip().lower().replace(":", "").replace("-", "")
+    if len(raw) != 12:
+        raise ValueError("address must be 12 hex chars or aa:bb:cc:dd:ee:ff")
+    try:
+        return bytes.fromhex(raw)
+    except ValueError:
+        raise ValueError("address contains non-hex characters")
+
+
+def format_mac(mac_bytes):
+    return ":".join("{:02x}".format(b) for b in mac_bytes)
+
+
+def print_bridge_ip(ws_port=80):
+    import network
+
+    try:
+        port = int(ws_port)
+    except (TypeError, ValueError):
+        port = 80
+
+    ips = []
+    try:
+        sta = network.WLAN(network.STA_IF)
+        if sta.active():
+            ip = sta.ifconfig()[0]
+            if ip and ip != "0.0.0.0":
+                ips.append(("STA", ip))
+    except Exception:
+        pass
+    try:
+        ap = network.WLAN(network.AP_IF)
+        if ap.active():
+            ip = ap.ifconfig()[0]
+            if ip and ip != "0.0.0.0":
+                ips.append(("AP", ip))
+    except Exception:
+        pass
+
+    if not ips:
+        print("bridge IP: (AP not up)")
+        return
+
+    ips.sort(key=lambda x: 0 if x[0] == "AP" else 1)
+    _label, ip = ips[0]
+    print("bridge IP (AP):", ip)
+    print("bridge_ws_url: ws://%s:%s/ws" % (ip, port))