chore(git): stop tracking runtime db state files

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

.cursor/rules/commit.mdc

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

.cursor/rules/led-driver.mdc

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

.cursor/rules/pattern-workflow.mdc

@@ -0,0 +1,12 @@
+---
+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.
+
+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.

.cursor/rules/scoped-fixes.mdc

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

.cursor/rules/spelling.mdc

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

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

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

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

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

.gitignore

@@ -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,7 +25,12 @@ ENV/
 Thumbs.db
 
 # Project specific
+scripts/.led-controller-venv
+docs/.help-print.html
+settings.json
+db/
 *.log
 *.db
 *.sqlite
-
+.pytest_cache/
+.ropeproject/

.gitmodules

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

Pipfile

@@ -12,13 +12,21 @@ watchfiles = "*"
 requests = "*"
 selenium = "*"
 adafruit-ampy = "*"
+microdot = "*"
+websockets = "*"
 
 [dev-packages]
+pytest = "*"
 
 [requires]
-python_version = "3.12"
+python_version = "3.11"
 
 [scripts]
-web = "python /home/pi/led-controller/tests/web.py"
+web = "python tests/web.py"
-watch = "python -m watchfiles 'python tests/web.py' src tests"
+watch = "python -m watchfiles \"python tests/web.py\" src tests"
-install = "pipenv install"
+run = "sh -c 'cd src && python main.py'"
+dev = "python -m watchfiles \"sh -c 'cd src && python main.py'\" src"
+test = "python -m pytest"
+test-browser = "sh -c 'python tests/web.py > /tmp/led-controller-web.log 2>&1 & pid=$!; trap \"kill $pid\" EXIT; sleep 2; LED_CONTROLLER_RUN_BROWSER_TESTS=1 LED_CONTROLLER_DEVICE_IP=http://127.0.0.1:5000 python -m pytest tests/test_browser.py'"
+test-browser-device = "sh -c 'LED_CONTROLLER_RUN_BROWSER_TESTS=1 python -m pytest tests/test_browser.py'"
+

README.md

@@ -1,2 +1,43 @@
 # led-controller
 
+LED controller web app for managing profiles, **zones**, presets, and colour palettes, and sending commands to LED devices. Outbound paths include:
+
+- **Serial → ESP-NOW bridge**: JSON lines over UART to an ESP32 that forwards ESP-NOW frames (configure `serial_port` and baud in `settings.json` / Settings model).
+- **Wi-Fi LED drivers**: TCP JSON lines (default port **8765** on the Pi; drivers discover the controller via **UDP 8766** broadcast).
+
+## Run
+
+- One-time setup for port 80 without root: `sudo scripts/setup-port80.sh`
+- Start app: `pipenv run run` (override listen port with the **`PORT`** environment variable)
+- Dev watcher (auto-restart on `src/` changes): `pipenv run dev`
+- Regenerate **`docs/help.pdf`** from **`docs/help.md`**: `pipenv run help-pdf` (requires **pandoc** and **chromium** on the host)
+
+## UI modes
+
+- **Run mode**: focused control view. Select zones/presets and apply profiles. Editing actions are hidden.
+- **Edit mode**: management view. Shows **Zones**, Presets, Patterns, Colour Palette, and Send Presets controls, plus per-tile preset edit/remove and drag-reorder.
+
+## Profiles
+
+- Applying a profile updates session scope and refreshes the active zone content.
+- In **Run mode**, Profiles supports apply-only behaviour (no create/clone/delete).
+- In **Edit mode**, Profiles supports create/clone/delete.
+- Creating a profile always creates a populated `default` zone (starter presets).
+- Optional **DJ zone** seeding creates:
+  - `dj` zone bound to device name `dj`
+  - starter DJ presets (rainbow, single colour, transition)
+
+## Preset colours and palette linking
+
+- In preset editor, selecting a colour picker value auto-adds it when the picker closes.
+- Use **From Palette** to add a palette-linked preset colour.
+- Linked colours are stored as palette references and shown with a `P` badge.
+- When profile palette colours change, linked preset colours update across that profile.
+
+## API docs
+
+- Main API reference: `docs/API.md`
+
+## Driver pattern modules
+
+Pattern **`.py`** sources live under **`led-driver/src/patterns`**. The Pi app resolves that path via `util.driver_patterns.driver_patterns_dir()`. If you deploy without that tree next to the app, set **`LED_CONTROLLER_PATTERNS_DIR`** to the directory that contains those files.

clear-debug-log.sh

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

db/group.json

@@ -1,17 +1 @@
-{
+{"1": {"name": "Main Group", "devices": ["1", "2", "3"]}, "2": {"name": "Accent Group", "devices": ["4", "5"]}}
-    "1": {
-        "name": "Main Group",
-        "devices": [
-            "1",
-            "2",
-            "3"
-        ]
-    },
-    "2": {
-        "name": "Accent Group",
-        "devices": [
-            "4",
-            "5"
-        ]
-    }
-}

db/palette.json

@@ -1,12 +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"
-    ]
-}

db/pattern.json

@@ -1,54 +1 @@
-{
+{"on": {"min_delay": 10, "max_delay": 10000, "max_colors": 1}, "off": {"min_delay": 10, "max_delay": 10000, "max_colors": 0}, "rainbow": {"n1": "Step Rate", "min_delay": 10, "max_delay": 10000, "max_colors": 0}, "colour_cycle": {"n1": "Step Rate", "min_delay": 10, "max_delay": 10000, "max_colors": 10}, "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, "has_background": true}, "pulse": {"n1": "Attack", "n2": "Hold", "n3": "Decay", "min_delay": 10, "max_delay": 10000, "max_colors": 10, "has_background": 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}, "blink": {"min_delay": 10, "max_delay": 10000, "max_colors": 10, "has_background": true}, "flicker": {"n1": "Min brightness", "min_delay": 10, "max_delay": 10000, "max_colors": 10}, "flame": {"n1": "Min brightness", "n2": "Breath period (ms)", "n3": "Spark gap min (ms, 0=default 10–30 s, -1=off)", "n4": "Spark gap max (ms)", "min_delay": 10, "max_delay": 10000, "max_colors": 10}, "twinkle": {"n1": "Twinkle activity (1–255, higher = more changes)", "n2": "Density (0–255, 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}, "radiate": {"n1": "Node spacing (LEDs)", "n2": "Out time (ms)", "n3": "In time (ms)", "min_delay": 10, "max_delay": 10000, "max_colors": 2, "has_background": true}, "meteor_rain": {"n1": "Tail length", "n2": "Speed (LEDs per frame)", "n3": "Fade amount (1-255)", "min_delay": 10, "max_delay": 10000, "max_colors": 10}, "scanner": {"n1": "Eye width", "n2": "End pause (frames)", "min_delay": 10, "max_delay": 10000, "max_colors": 10, "has_background": true}, "gradient_scroll": {"n1": "Scroll step rate", "min_delay": 10, "max_delay": 10000, "max_colors": 10}, "comet_dual": {"n1": "Tail length", "n2": "Speed", "n3": "Gap", "max_colors": 10, "min_delay": 10, "max_delay": 10000, "has_background": true}, "sparkle_trail": {"n1": "Spark density", "n2": "Decay", "max_colors": 10, "min_delay": 10, "max_delay": 10000}, "wave": {"n1": "Wavelength", "n2": "Amplitude", "n3": "Drift speed", "max_colors": 10, "min_delay": 10, "max_delay": 10000}, "plasma": {"n1": "Scale", "n2": "Speed", "n3": "Contrast", "max_colors": 10, "min_delay": 10, "max_delay": 10000}, "segment_chase": {"n1": "Segment size", "n2": "Phase step", "n3": "Segment phase offset", "n4": "Gap per segment", "max_colors": 10, "min_delay": 10, "max_delay": 10000, "has_background": true}, "bar_graph": {"n1": "Level percent", "max_colors": 10, "min_delay": 10, "max_delay": 10000, "has_background": true}, "breathing_dual": {"n1": "Phase offset", "n2": "Ease", "max_colors": 10, "min_delay": 10, "max_delay": 10000}, "strobe_burst": {"n1": "Burst count", "n2": "Burst gap", "n3": "Cooldown", "max_colors": 10, "min_delay": 10, "max_delay": 10000, "has_background": true}, "rain_drops": {"n1": "Drop rate", "n2": "Ripple width", "max_colors": 10, "min_delay": 10, "max_delay": 10000, "has_background": true}, "fireflies": {"n1": "Count", "n2": "Twinkle speed", "max_colors": 10, "min_delay": 10, "max_delay": 10000, "has_background": true}, "clock_sweep": {"n1": "Hand width", "n2": "Marker interval", "max_colors": 10, "min_delay": 10, "max_delay": 10000, "has_background": true}, "marquee": {"n1": "On length", "n2": "Off length", "n3": "Step", "max_colors": 10, "min_delay": 10, "max_delay": 10000, "has_background": true}, "aurora": {"n1": "Band count", "n2": "Shimmer", "max_colors": 10, "min_delay": 10, "max_delay": 10000}, "snowfall": {"n1": "Flake density", "n2": "Fall speed", "max_colors": 10, "min_delay": 10, "max_delay": 10000, "has_background": true}, "heartbeat": {"n1": "Pulse 1 ms", "n2": "Pulse 2 ms", "n3": "Pause ms", "max_colors": 10, "min_delay": 10, "max_delay": 10000, "has_background": true}, "orbit": {"n1": "Orbit count", "n2": "Base speed", "max_colors": 10, "min_delay": 10, "max_delay": 10000, "has_background": true}, "palette_morph": {"n1": "Morph ms", "n2": "Warp rate", "n3": "Turbulence", "max_colors": 10, "min_delay": 10, "max_delay": 10000}}
-    "on": {
-            "min_delay": 10,
-            "max_delay": 10000,
-            "max_colors": 1
-        },
-    "off": {
-        "min_delay": 10,
-        "max_delay": 10000,
-        "max_colors": 0
-    },
-    "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
-    }
-}

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,11 +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": "tabs",
-    "tabs": [
-      "1"
-    ],
-    "scenes": [],
-    "palette_id": "1"
-  }
-}

db/sequence.json

@@ -1,30 +1 @@
-{
+{"1": {"group_name": "Main Group", "presets": ["1", "2"], "sequence_duration": 3000, "sequence_transition": 500, "sequence_loop": true, "sequence_repeat_count": 0, "sequence_active": false, "sequence_index": 0, "sequence_start_time": 0}, "2": {"group_name": "Accent Group", "presets": ["2", "3"], "sequence_duration": 2000, "sequence_transition": 300, "sequence_loop": true, "sequence_repeat_count": 0, "sequence_active": false, "sequence_index": 0, "sequence_start_time": 0}}
-    "1": {
-        "group_name": "Main Group",
-        "presets": [
-            "1",
-            "2"
-        ],
-        "sequence_duration": 3000,
-        "sequence_transition": 500,
-        "sequence_loop": true,
-        "sequence_repeat_count": 0,
-        "sequence_active": false,
-        "sequence_index": 0,
-        "sequence_start_time": 0
-    },
-    "2": {
-        "group_name": "Accent Group",
-        "presets": [
-            "2",
-            "3"
-        ],
-        "sequence_duration": 2000,
-        "sequence_transition": 300,
-        "sequence_loop": true,
-        "sequence_repeat_count": 0,
-        "sequence_active": false,
-        "sequence_index": 0,
-        "sequence_start_time": 0
-    }
-}

db/tab.json

@@ -1,27 +0,0 @@
-{
-  "1": {
-    "name": "default",
-    "names": [
-      "1","2","3","4","5","6","7","8"
-    ],
-    "presets": [
-      [
-        "1",
-        "2",
-        "3",
-        "4",
-        "5",
-        "6",
-        "7",
-        "8",
-        "9",
-        "10",
-        "11",
-        "12",
-        "13",
-        "14",
-        "15"
-      ]
-    ]
-  }
-}

dev.py

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

docs/API.md

@@ -1,263 +1,358 @@
-# LED Driver ESPNow API Documentation
+# LED Controller API
 
-This document describes the ESPNow message format for controlling LED driver devices.
+This document covers:
 
-## Message Format
+1. **HTTP and WebSocket** exposed by the Raspberry Pi app (`src/main.py`) — profiles, zones, presets, transport send, pattern OTA helpers, and related resources.
+2. **LED driver JSON** — the compact **v1** message format. It is sent over the **serial → ESP-NOW bridge** to ESP32 peers and as **single JSON text messages** over the **outbound WebSocket** to **Wi-Fi** drivers (same logical fields).
 
-All messages are JSON objects sent via ESPNow with the following structure:
+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.
+
+---
+
+## UI behavior notes
+
+The main UI has two modes controlled by the mode toggle:
+
+- **Run mode**: optimized for operation (zone/preset selection and profile apply).
+- **Edit mode**: shows editing/management controls (zones, presets, patterns, colour palette, send presets, profile management actions, **Devices** registry for LED driver names/MACs, and related tools).
+
+Profiles are available in both modes, but behavior differs:
+
+- **Run mode**: profile **apply** only.
+- **Edit mode**: profile **create/clone/delete/apply**.
+
+`POST /presets/send` is wired to the **Send Presets** UI action, which is exposed in Edit mode.
+
+---
+
+## Session and scoping
+
+Several routes use **`@with_session`**: the server stores a **current profile** in the session (cookie). Endpoints that scope data to “the current profile” (notably **`/presets`**) only return or mutate presets whose `profile_id` matches that session value.
+
+Profiles are selected with **`POST /profiles/<id>/apply`**, which sets `current_profile` in the session.
+
+---
+
+## Static pages and assets
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | Main UI (`templates/index.html`) |
+| GET | `/settings/page` | Standalone settings page (`templates/settings.html`) |
+| GET | `/favicon.ico` | Empty response (204) |
+| GET | `/static/<path>` | Static files under `src/static/` |
+
+---
+
+## WebSocket: `/ws`
+
+Connect to **`ws://<host>:<port>/ws`**.
+
+- Send **JSON**: the object is forwarded through the **serial sender** (6-byte MAC prefix + payload to the ESP-NOW bridge). Optional key **`to`**: 12-character hex MAC address; if present it is removed from the object and the payload is sent to that peer; otherwise the default destination from settings is used.
+- Send **non-JSON text**: forwarded as raw bytes with the default address.
+- On send failure, the server may reply with `{"error": "Send failed"}`.
+
+Wi-Fi devices are not targeted by `/ws` directly; use **`POST /presets/send`**, device routes, or **`POST /patterns/<name>/send`** as appropriate.
+
+---
+
+## HTTP API by resource
+
+Below, `<id>` values are string identifiers used by the JSON stores (numeric strings in practice).
+
+### Settings — `/settings`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/settings` | Full settings object (from `settings.json` / `Settings` model). |
+| PUT | `/settings/settings` | Merge keys into settings and save. Returns `{"message": "Settings updated successfully"}`. |
+| GET | `/settings/wifi/ap` | Saved Wi‑Fi AP fields: `saved_ssid`, `saved_password`, `saved_channel`, `active` (Pi: `active` is always false). |
+| POST | `/settings/wifi/ap` | Body: `ssid` (required), `password`, `channel` (1–11). Persists AP-related settings. |
+| GET | `/settings/page` | Serves `templates/settings.html`. |
+
+### Devices — `/devices`
+
+Registry in `db/device.json`: storage key **`<id>`** (string, e.g. `"1"`) maps to an object that always includes:
+
+| Field | Description |
+|-------|-------------|
+| **`id`** | Same as the storage key (stable handle for URLs). |
+| **`name`** | Shown in the UI and used in `select` keys. |
+| **`type`** | `led` (only value today; extensible). |
+| **`transport`** | `espnow` or `wifi`. |
+| **`address`** | For **`espnow`**: optional 12-character lowercase hex MAC. For **`wifi`**: optional IP or hostname string. |
+| **`default_pattern`**, **`zones`** | Optional. Legacy **`tabs`** may still appear in old files and is migrated away on load. |
+
+Existing records without `type` / `transport` / `id` are backfilled on load (`led`, `espnow`, and `id` = key).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/devices` | Map of device id → device object. |
+| GET | `/devices/<id>` | One device, 404 if missing. |
+| POST | `/devices` | Create. Body: **`name`** (required), **`type`** (default `led`), **`transport`** (default `espnow`), optional **`address`**, **`default_pattern`**, **`zones`**. Returns `{ "<id>": { ... } }`, 201. |
+| PUT | `/devices/<id>` | Partial update. **`name`** cannot be cleared. **`id`** in the body is ignored. **`type`** / **`transport`** validated; **`address`** normalised for the resulting transport. |
+| DELETE | `/devices/<id>` | Remove device. |
+
+### Profiles — `/profiles`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/profiles` | `{"profiles": {...}, "current_profile_id": "<id>"}`. Ensures a default current profile when possible. |
+| GET | `/profiles/current` | `{"id": "...", "profile": {...}}` |
+| GET | `/profiles/<id>` | Single profile. If `<id>` is `current`, same as `/profiles/current`. |
+| POST | `/profiles` | Create profile. Body may include `name` and other fields. Optional `seed_dj_zone` (request-only) seeds a DJ zone + presets. New profiles always get a populated `default` zone. Returns `{ "<id>": { ... } }` with status 201. |
+| POST | `/profiles/<id>/apply` | Sets session current profile to `<id>`. |
+| POST | `/profiles/<id>/clone` | Clone profile (zones, palettes, presets). Body may include `name`. |
+| PUT | `/profiles/current` | Update the current profile (from session). |
+| PUT | `/profiles/<id>` | Update profile by id. |
+| DELETE | `/profiles/<id>` | Delete profile. |
+
+### Presets — `/presets`
+
+Scoped to **current profile** in session (see above).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/presets` | Map of preset id → preset object for the current profile only. |
+| GET | `/presets/<id>` | One preset, 404 if missing or wrong profile. |
+| POST | `/presets` | Create preset; server assigns id and sets `profile_id`. Body fields stored on the preset. Returns `{ "<id>": { ... } }`, 201. |
+| PUT | `/presets/<id>` | Update preset (must belong to current profile). |
+| DELETE | `/presets/<id>` | Delete preset. |
+| POST | `/presets/send` | Push presets to the LED driver over the configured transport (see below). |
+
+**`POST /presets/send` body:**
+
+```json
+{
+  "preset_ids": ["1", "2"],
+  "save": true,
+  "default": "1",
+  "destination_mac": "aabbccddeeff"
+}
+```
+
+- **`preset_ids`** (or **`ids`**): non-empty list of preset ids to include.
+- **`save`**: if true, the outgoing message includes `"save": true` so the driver may persist presets (default true).
+- **`default`**: optional preset id string; forwarded as top-level `"default"` in the driver message (startup selection on device).
+- **`destination_mac`** (or **`to`**): optional 12-character hex MAC for unicast; omitted uses the transport default (e.g. broadcast).
+
+Response on success includes `presets_sent`, `messages_sent` (chunking splits payloads so each JSON string stays ≤ 240 bytes).
+
+Stored preset records can include:
+
+- `colors`: resolved hex colours for editor/display.
+- `palette_refs`: optional array of palette indexes parallel to `colors`. If a slot contains an integer index, the colour is linked to the current profile palette at that index.
+
+### Zones — `/zones`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/zones` | `zones` (map of zone id → zone object), `zone_order`, `current_zone_id`, `profile_id` for the session-backed profile. |
+| GET | `/zones/current` | Current zone from cookie/session. |
+| POST | `/zones` | Create zone; optional JSON `name`, `names`, `presets`; can append to current profile’s zone list. |
+| GET | `/zones/<id>` | Zone JSON. |
+| PUT | `/zones/<id>` | Update zone. |
+| DELETE | `/zones/<id>` | Delete zone; can delete `current` to remove the active zone; updates profile zone list. |
+| POST | `/zones/<id>/set-current` | Sets `current_zone` cookie. |
+| POST | `/zones/<id>/clone` | Clone zone into current profile. |
+
+### Palettes — `/palettes`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/palettes` | Map of id → colour list. |
+| GET | `/palettes/<id>` | `{"colors": [...], "id": "<id>"}` |
+| POST | `/palettes` | Body may include `colors`. Returns palette object with `id`, 201. |
+| PUT | `/palettes/<id>` | Update colours (`name` ignored). |
+| DELETE | `/palettes/<id>` | Delete palette. |
+
+### Groups — `/groups`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/groups` | All groups. |
+| GET | `/groups/<id>` | One group. |
+| POST | `/groups` | Create; optional `name` and fields. |
+| PUT | `/groups/<id>` | Update. |
+| DELETE | `/groups/<id>` | Delete. |
+
+### Scenes — `/scenes`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/scenes` | All scenes. |
+| GET | `/scenes/<id>` | One scene. |
+| POST | `/scenes` | Create (body JSON stored on scene). |
+| PUT | `/scenes/<id>` | Update. |
+| DELETE | `/scenes/<id>` | Delete. |
+
+### Sequences — `/sequences`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/sequences` | All sequences. |
+| GET | `/sequences/<id>` | One sequence. |
+| POST | `/sequences` | Create; may use `group_name`, `presets` in body. |
+| PUT | `/sequences/<id>` | Update. |
+| DELETE | `/sequences/<id>` | Delete. |
+
+### Patterns — `/patterns`
+
+Pattern metadata lives in **`db/pattern.json`**; driver source files live under **`led-driver/src/patterns/`**. Several routes expose a **runtime map** (metadata merged with on-disk `.py` names so new files appear in menus).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/patterns` | Runtime pattern map (object keyed by pattern id). |
+| GET | `/patterns/definitions` | Same runtime map (intended for UI “definitions” clients). |
+| GET | `/patterns/ota/manifest` | JSON `{"files":[{"name":"blink.py","url":"http://<Host>/patterns/ota/file/blink.py"},...]}` for OTA pulls. Requires **`Host`** header. |
+| GET | `/patterns/ota/file/<name>` | Raw **`.py`** source for one driver pattern (`name` must be a safe filename, e.g. `rainbow.py`). |
+| POST | `/patterns/<name>/send` | Push a **manifest** JSON line to **Wi-Fi** devices so they pull one pattern file over HTTP. Body may include **`device_id`** to target one device; otherwise all Wi-Fi devices with an **`address`** are tried. **`<name>`** may be with or without `.py`. |
+| POST | `/patterns/upload` | Body JSON: **`name`**, **`code`**, optional **`overwrite`** (default true). Writes **`led-driver/src/patterns/<name>.py`**. |
+| POST | `/patterns/driver` | Body JSON: **`name`** (identifier), **`code`**, optional metadata (`min_delay`, `max_delay`, `max_colors`, `n1`…`n8`, **`overwrite`**). Creates/updates both the **`.py`** file and **`db/pattern.json`** via the Pattern model. |
+| GET | `/patterns/<id>` | One pattern record from the Pattern model (metadata only). |
+| POST | `/patterns` | Create (`name`, optional `data`). |
+| PUT | `/patterns/<id>` | Update. |
+| DELETE | `/patterns/<id>` | Delete. |
+
+**Devices — pattern OTA push**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/devices/<id>/patterns/push` | Wi-Fi only. Asks the driver at **`address`** to pull pattern files from this server. Optional body **`manifest`**: either a **URL string** pointing at a manifest JSON document, or a **manifest object** (same shape as in driver messages). If omitted, a default manifest is built from the request **`Host`** header. |
+
+---
+
+## LED driver message format (transport / ESP-NOW / Wi-Fi)
+
+Messages are JSON objects. The Pi **`build_message()`** helper (`src/util/espnow_message.py`) produces the same shape sent over serial and forwarded by the ESP32 bridge, and the same logical object can be sent as a **single JSON text message** to a Wi-Fi driver over the **WebSocket**.
+
+### Top-level fields
 
 ```json
 {
   "v": "1",
-  "presets": { ... },
+  "presets": { },
-  "select": { ... }
+  "select": { },
+  "save": true,
+  "default": "preset_id",
+  "b": 255
 }
 ```
 
-### Version Field
+- **`v`** (required): Must be `"1"` or the driver ignores the message.
+- **`presets`**: Map of **preset id** (string) → preset object (see below). Optional **`name`** field on each value is accepted for display; the driver keys presets by map key.
+- **`select`**: Map of **device name** (as in device settings) → `[ "preset_id" ]` or `[ "preset_id", step ]`.
+- **`save`**: If present (e.g. true), the driver may persist presets to flash after applying.
+- **`default`**: Preset id string to use as startup default on the device.
+- **`b`**: Optional **global** brightness 0–255 (driver applies this in addition to per-preset brightness).
 
-- **`v`** (required): Message version, must be `"1"`. Messages with other versions are ignored.
+### Preset object (wire / driver keys)
 
-## Presets
+On the wire, presets use **short keys** (saves space in the ≤240-byte chunks):
 
-Presets define LED patterns with their configuration. Each preset has a name and contains pattern-specific settings.
+| Key | Meaning | Notes |
+|-----|---------|--------|
+| `p` | Pattern id | `off`, `on`, `blink`, `rainbow`, `pulse`, `transition`, `chase`, `circle` |
+| `c` | Colours | Array of `"#RRGGBB"` hex strings; converted to RGB on device |
+| `d` | Delay ms | Default 100 |
+| `b` | Preset brightness | 0–255; combined with global `b` on the device |
+| `a` | Auto | `true`: run continuously; `false`: one step/cycle per “beat” |
+| `n1`–`n6` | Pattern parameters | See below |
 
-### Preset Structure
+The HTTP app’s **`POST /presets/send`** path builds this from stored presets via **`build_preset_dict()`** (long names like `pattern` / `colors` in the DB are translated to `p` / `c` / …).
 
-```json
+### Pattern-specific parameters (`n1`–`n6`)
-{
-  "presets": {
-    "preset_name": {
-      "pattern": "pattern_type",
-      "colors": ["#RRGGBB", ...],
-      "delay": 100,
-      "brightness": 127,
-      "auto": true,
-      "n1": 0,
-      "n2": 0,
-      "n3": 0,
-      "n4": 0,
-      "n5": 0,
-      "n6": 0
-    }
-  }
-}
-```
-
-### Preset Fields
-
-- **`pattern`** (required): Pattern type. Options:
-  - `"off"` - Turn off all LEDs
-  - `"on"` - Solid color
-  - `"blink"` - Blinking pattern
-  - `"rainbow"` - Rainbow color cycle
-  - `"pulse"` - Pulse/fade pattern
-  - `"transition"` - Color transition
-  - `"chase"` - Chasing pattern
-  - `"circle"` - Circle loading pattern
-
-- **`colors`** (optional): Array of hex color strings (e.g., `"#FF0000"` for red). Default: `["#FFFFFF"]`
-  - Colors are automatically converted from hex to RGB and reordered based on device color order setting
-  - Supports multiple colors for patterns that use them
-
-- **`delay`** (optional): Delay in milliseconds between pattern updates. Default: `100`
-
-- **`brightness`** (optional): Brightness level (0-255). Default: `127`
-
-- **`auto`** (optional): Auto mode flag. Default: `true`
-  - `true`: Pattern runs continuously
-  - `false`: Pattern advances one step per beat (manual mode)
-
-- **`n1` through `n6`** (optional): Pattern-specific numeric parameters. Default: `0`
-  - See pattern-specific documentation below
-
-### Pattern-Specific Parameters
 
 #### Rainbow
-- **`n1`**: Step increment (how many color wheel positions to advance per update). Default: `1`
+- **`n1`**: Step increment on the colour wheel per update (default 1).
 
 #### Pulse
-- **`n1`**: Attack time in milliseconds (fade in)
+- **`n1`**: Attack (fade in) ms  
-- **`n2`**: Hold time in milliseconds (full brightness)
+- **`n2`**: Hold ms  
-- **`n3`**: Decay time in milliseconds (fade out)
+- **`n3`**: Decay (fade out) ms  
-- **`delay`**: Delay time in milliseconds (off between pulses)
+- **`d`**: Off time between pulses ms  
 
 #### Transition
-- **`delay`**: Transition duration in milliseconds
+- **`d`**: Transition duration ms  
 
 #### Chase
-- **`n1`**: Number of LEDs with first color
+- **`n1`**: LEDs with first colour  
-- **`n2`**: Number of LEDs with second color
+- **`n2`**: LEDs with second colour  
-- **`n3`**: Movement amount on even steps (can be negative)
+- **`n3`**: Movement on even steps (may be negative)  
-- **`n4`**: Movement amount on odd steps (can be negative)
+- **`n4`**: Movement on odd steps (may be negative)  
 
 #### Circle
-- **`n1`**: Head movement rate (LEDs per second)
+- **`n1`**: Head speed (LEDs/s)  
-- **`n2`**: Maximum length
+- **`n2`**: Max length  
-- **`n3`**: Tail movement rate (LEDs per second)
+- **`n3`**: Tail speed (LEDs/s)  
-- **`n4`**: Minimum length
+- **`n4`**: Min length  
 
-## Select Messages
+### Select messages
-
-Select messages control which preset is active on which device. The format uses a list to support step synchronization.
-
-### Select Format
 
 ```json
 {
   "select": {
-    "device_name": ["preset_name"],
+    "device_name": ["preset_id"],
-    "device_name2": ["preset_name2", step_value]
+    "other_device": ["preset_id", 10]
   }
 }
 ```
 
-### Select Fields
+- One element: select preset; step behavior follows driver rules (reset on `off`, etc.).
+- Two elements: explicit **step** for sync.
 
-- **`select`**: Object mapping device names to selection lists
+### Beat and sync behavior
-  - **Key**: Device name (as configured in device settings)
-  - **Value**: List with one or two elements:
-    - `["preset_name"]` - Select preset (uses default step behavior)
-    - `["preset_name", step]` - Select preset with explicit step value (for synchronization)
 
-### Step Synchronization
+- Sending **`select`** again with the **same** preset name acts as a **beat** (advances manual patterns / restarts generators per driver logic).
+- Choosing **`off`** resets step as a sync point; then selecting a pattern aligns step 0 across devices unless a step is passed explicitly.
 
-The step value allows precise synchronization across multiple devices:
+### Example (compact preset map)
-
-- **Without step**: `["preset_name"]`
-  - If switching to different preset: step resets to 0
-  - If selecting "off" pattern: step resets to 0
-  - If selecting same preset (beat): step is preserved, pattern restarts
-
-- **With step**: `["preset_name", 10]`
-  - Explicitly sets step to the specified value
-  - Useful for synchronizing multiple devices to the same step
-
-### Beat Functionality
-
-Calling `select()` again with the same preset name acts as a "beat" - it restarts the pattern generator:
-
-- **Single-tick patterns** (rainbow, chase in manual mode): Advance one step per beat
-- **Multi-tick patterns** (pulse in manual mode): Run through full cycle per beat
-
-Example beat sequence:
-```json
-// Beat 1
-{"select": {"device1": ["rainbow_preset"]}}
-
-// Beat 2 (same preset = beat)
-{"select": {"device1": ["rainbow_preset"]}}
-
-// Beat 3
-{"select": {"device1": ["rainbow_preset"]}}
-```
-
-## Synchronization
-
-### Using "off" Pattern
-
-Selecting the "off" pattern resets the step counter to 0, providing a synchronization point:
-
-```json
-{
-  "select": {
-    "device1": ["off"],
-    "device2": ["off"]
-  }
-}
-```
-
-After all devices are "off", switching to a pattern ensures they all start from step 0:
-
-```json
-{
-  "select": {
-    "device1": ["rainbow_preset"],
-    "device2": ["rainbow_preset"]
-  }
-}
-```
-
-### Using Step Parameter
-
-For precise synchronization, use the step parameter:
-
-```json
-{
-  "select": {
-    "device1": ["rainbow_preset", 10],
-    "device2": ["rainbow_preset", 10],
-    "device3": ["rainbow_preset", 10]
-  }
-}
-```
-
-All devices will start at step 10 and advance together on subsequent beats.
-
-## Complete Example
 
 ```json
 {
   "v": "1",
+  "save": true,
   "presets": {
-    "red_blink": {
+    "1": {
-      "pattern": "blink",
+      "name": "Red blink",
-      "colors": ["#FF0000"],
+      "p": "blink",
-      "delay": 200,
+      "c": ["#FF0000"],
-      "brightness": 255,
+      "d": 200,
-      "auto": true
+      "b": 255,
-    },
+      "a": true,
-    "rainbow_manual": {
+      "n1": 0, "n2": 0, "n3": 0, "n4": 0, "n5": 0, "n6": 0
-      "pattern": "rainbow",
-      "delay": 100,
-      "n1": 2,
-      "auto": false
-    },
-    "pulse_slow": {
-      "pattern": "pulse",
-      "colors": ["#00FF00"],
-      "delay": 500,
-      "n1": 1000,
-      "n2": 500,
-      "n3": 1000,
-      "auto": false
     }
   },
   "select": {
-    "device1": ["red_blink"],
+    "living-room": ["1"]
-    "device2": ["rainbow_manual", 0],
-    "device3": ["pulse_slow"]
   }
 }
 ```
 
-## Message Processing
+---
 
-1. **Version Check**: Messages with `v != "1"` are rejected
+## Processing summary (driver)
-2. **Preset Processing**: Presets are created or updated (upsert behavior)
-3. **Color Conversion**: Hex colors are converted to RGB tuples and reordered based on device color order
-4. **Selection**: Devices select their assigned preset, optionally with step value
 
-## Best Practices
+1. Reject if `v != "1"`.
+2. Apply optional top-level **`b`** (global brightness).
+3. For each entry in **`presets`**, normalize colours and upsert preset by id.
+4. If this device’s **`name`** appears in **`select`**, run selection (optional step).
+5. If **`default`** is set, store startup preset id.
+6. If **`save`** is set, persist presets.
 
-1. **Always include version**: Set `"v": "1"` in all messages
+---
-2. **Use "off" for sync**: Select "off" pattern to synchronize devices before starting patterns
-3. **Beats for manual mode**: Send select messages repeatedly with same preset name to advance manual patterns
-4. **Step for precision**: Use step parameter when exact synchronization is required
-5. **Color format**: Always use hex strings (`"#RRGGBB"`), conversion is automatic
 
-## Error Handling
+## Error handling (HTTP)
 
-- Invalid version: Message is ignored
+Controllers typically return JSON with an **`error`** string and 4xx/5xx status codes. Invalid JSON bodies often yield `{"error": "Invalid JSON"}`.
-- Missing preset: Selection fails, device keeps current preset
+
-- Invalid pattern: Selection fails, device keeps current preset
+---
-- Missing colors: Pattern uses default white color
-- Invalid step: Step value is used as-is (may cause unexpected behavior)
 
 ## Notes
 
-- Colors are automatically converted from hex strings to RGB tuples
+- **Human-readable preset fields** (`pattern`, `colors`, `delay`, …) are fine in the **web app / database**; the **send path** converts them to **`p` / `c` / `d`** for the driver.
-- Color order reordering happens automatically based on device settings
+- For a copy of the older long-key reference, see **`led-driver/docs/API.md`** in this repo (conceptually the same behavior; wire format prefers short keys).
-- Step counter wraps around (0-255 for rainbow, unbounded for others)
-- Manual mode patterns stop after one step/cycle, waiting for next beat
-- Auto mode patterns run continuously until changed

docs/SPECIFICATION.md

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

docs/help.md

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

docs/images/help/colour-palette.svg

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

docs/images/help/header-toolbar.svg

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

docs/images/help/mobile-menu.svg

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

docs/images/help/preset-editor.svg

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

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

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

docs/mockups/COLOR_PICKER_README.md

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

docs/mockups/device-management.html

@@ -67,7 +67,7 @@
             box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
         }
 
-        .tab {
+        .zone {
             flex: 1;
             padding: 12px 24px;
             border: none;
@@ -78,16 +78,16 @@
             transition: all 0.2s;
         }
 
-        .tab.active {
+        .zone.active {
             background: #667eea;
             color: white;
         }
 
-        .tab-content {
+        .zone-content {
             display: none;
         }
 
-        .tab-content.active {
+        .zone-content.active {
             display: block;
         }
 
@@ -249,12 +249,12 @@
         </div>
 
         <div class="tabs">
-            <button class="tab active" onclick="switchTab('devices')">Devices</button>
+            <button class="zone active" onclick="switchTab('devices')">Devices</button>
-            <button class="tab" onclick="switchTab('groups')">Groups</button>
+            <button class="zone" onclick="switchTab('groups')">Groups</button>
         </div>
 
-        <!-- Devices Tab -->
+        <!-- Devices Zone -->
-        <div id="devices-tab" class="tab-content active">
+        <div id="devices-zone" class="zone-content active">
             <div class="card">
                 <h2>Connected Devices</h2>
                 <div class="device-item">
@@ -313,8 +313,8 @@
             </div>
         </div>
 
-        <!-- Groups Tab -->
+        <!-- Groups Zone -->
-        <div id="groups-tab" class="tab-content">
+        <div id="groups-zone" class="zone-content">
             <div class="card">
                 <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 20px;">
                     <h2>Groups</h2>
@@ -386,12 +386,12 @@
     </div>
 
     <script>
-        function switchTab(tab) {
+        function switchTab(zone) {
-            document.querySelectorAll('.tab').forEach(t => t.classList.remove('active'));
+            document.querySelectorAll('.zone').forEach(t => t.classList.remove('active'));
-            document.querySelectorAll('.tab-content').forEach(c => c.classList.remove('active'));
+            document.querySelectorAll('.zone-content').forEach(c => c.classList.remove('active'));
             
             event.target.classList.add('active');
-            document.getElementById(tab + '-tab').classList.add('active');
+            document.getElementById(zone + '-zone').classList.add('active');
         }
 
         function showAddDeviceModal() {

docs/msg.json

@@ -1,30 +1,23 @@
 {
-    "grps": [
+    "g":{ 
-        {
+        "df": {
-            "n": "group1",
             "pt": "on",
-            "cl": [
+            "cl": ["#ff0000"],
-                "000000",
+            "br": 200,
-                "000000"
+            "n1": 10,
-            ],
+            "n2": 10,
-            "br": 100,
+            "n3": 10,
-            "dl": 100,
+            "n4": 10,
-            "n1": 0,
+            "n5": 10,
-            "n2": 0,
+            "n6": 10,
-            "n3": 0,
-            "n4": 0,
-            "n5": 0,
-            "n6": 0
-        },
-        {
-            "n": "group2",
-            "pt": "on",
-            "cl": [
-                "000000",
-                "000000"
-            ],
-            "br": 100,
             "dl": 100
+        },
+        "dj": {
+            "pt": "blink",
+            "cl": ["#00ff00"],
+            "dl": 500
         }
-    ]
+    },
+    "sv": true,
+    "st": 0
 }

espnow-sender/README.md

@@ -0,0 +1,7 @@
+# espnow-sender
+
+Minimal MicroPython project for receiving JSON over Microdot WebSocket.
+
+- WebSocket endpoint: `/ws`
+- Entry point: `main.py`
+- Message template: `msg.json`

espnow-sender/main.py

@@ -0,0 +1,120 @@
+import asyncio
+import json
+
+from microdot import Microdot
+from microdot.websocket import WebSocketError, with_websocket
+
+import espnow
+import network
+from util import format_mac, parse_mac
+
+
+app = Microdot()
+_esp = None
+_known_peers = set()
+_ws_clients = set()
+
+
+def _init_espnow():
+    global _esp
+    sta = network.WLAN(network.STA_IF)
+    sta.active(True)
+    _esp = espnow.ESPNow()
+    _esp.active(True)
+
+
+def _validate_envelope(obj):
+    if obj.get("v") != "1":
+        raise ValueError("message.v must be '1'")
+    devices = obj["devices"]
+    for address in devices.keys():
+        parse_mac(address)
+    return obj
+
+
+def _send_espnow(address, payload):
+    if _esp is None:
+        raise ValueError("espnow is not initialized")
+    mac = parse_mac(address)
+    msg = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+    if mac not in _known_peers:
+        _esp.add_peer(mac)
+        _known_peers.add(mac)
+    _esp.send(mac, msg)
+    return mac, len(msg)
+
+
+async def _broadcast_ws(obj):
+    text = json.dumps(obj)
+    dead = []
+    for client in list(_ws_clients):
+        try:
+            await client.send(text)
+        except Exception:
+            dead.append(client)
+    for client in dead:
+        _ws_clients.discard(client)
+
+
+async def _espnow_receive_loop():
+    while True:
+        host, msg = _esp.recv(0)
+        if not host:
+            await asyncio.sleep(0.01)
+            continue
+        await _broadcast_ws(
+            {
+                "from": format_mac(host),
+                "payload": msg.decode("utf-8"),
+            }
+        )
+
+
+@app.route("/ws")
+@with_websocket
+async def ws(request, ws):
+    _ws_clients.add(ws)
+    while True:
+        try:
+            raw = await ws.receive()
+        except WebSocketError:
+            break
+
+        if not raw:
+            break
+
+        try:
+            parsed = json.loads(raw)
+            env = _validate_envelope(parsed)
+            sent = []
+            for address, payload in env["devices"].items():
+                mac, payload_size = _send_espnow(address, payload)
+                sent.append(
+                    {
+                        "address": format_mac(mac),
+                        "bytes": payload_size,
+                    }
+                )
+        except (ValueError, TypeError) as e:
+            await ws.send(json.dumps({"ok": False, "error": str(e)}))
+            continue
+
+        await ws.send(
+            json.dumps(
+                {
+                    "ok": True,
+                    "sent": sent,
+                }
+            )
+        )
+    _ws_clients.discard(ws)
+
+
+async def main(port=80):
+    _init_espnow()
+    asyncio.create_task(_espnow_receive_loop())
+    await app.start_server(host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    asyncio.run(main(port=80))

espnow-sender/msg.json

@@ -0,0 +1,24 @@
+{
+    "v": "1",
+    "devices": {
+        "ff:ff:ff:ff:ff:ff": {
+            "presets": {
+                "preset_id": {
+                    "pattern": "on",
+                    "colors": ["#FF0000"],
+                    "delay": 100,
+                    "brightness": 255,
+                    "auto": true
+                }
+            }, 
+            "select": {
+                "preset": "preset_id",
+                "step": 0
+            }, 
+            "save": true, 
+            "default": "preset_id", 
+            "b": 255
+        }
+    }
+}
+    

espnow-sender/util.py

@@ -0,0 +1,12 @@
+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)

install.sh

@@ -1,4 +0,0 @@
-#!/usr/bin/env bash
-# Install script - runs pipenv install
-
-pipenv install "$@"

led_bar_vertical_stand.scad

@@ -0,0 +1,123 @@
+// Parametric LED bar vertical stand socket
+// For a bar nominally 14 x 17 mm, 2 m long.
+// This part is intended to be screwed to an MDF base.
+
+// -------------------------
+// User parameters
+// -------------------------
+bar_w = 14;                 // Bar width (mm)
+bar_d = 17;                 // Bar depth (mm)
+clearance = 0.4;            // Total clearance added to each axis (mm)
+
+socket_height = 36;         // Height of printed socket body (mm)
+wall = 3.2;                 // Socket wall thickness (mm)
+base_thickness = 5;         // Printed bottom plate thickness (mm)
+
+// USB cable/connector side opening
+usb_notch_enable = true;
+usb_notch_w = 11;
+usb_notch_h = 9;
+usb_notch_from_bottom = 6;
+usb_notch_side = "right";   // "right" or "left"
+
+// Mounting ears for MDF screws
+ear_enable = true;
+ear_len = 16;
+ear_w = 16;
+ear_thickness = base_thickness;
+screw_hole_d = 4.2;         // M4 clearance. Use 3.4 for M3.
+screw_hole_edge = 5.5;      // Hole center offset from ear outer corner
+
+// Optional clamp lip at top to reduce wobble
+top_lip_enable = true;
+top_lip_depth = 2.0;        // Intrudes into opening on each side
+top_lip_height = 3.0;
+
+$fn = 48;
+
+// -------------------------
+// Derived
+// -------------------------
+inner_w = bar_w + clearance;
+inner_d = bar_d + clearance;
+
+outer_w = inner_w + wall * 2;
+outer_d = inner_d + wall * 2;
+outer_h = socket_height;
+
+module screw_hole() {
+    cylinder(h = ear_thickness + 0.2, d = screw_hole_d);
+}
+
+module mounting_ear(sign_y = 1) {
+    translate([outer_w / 2, sign_y * (outer_d / 2), 0])
+    cube([ear_len, ear_w, ear_thickness], center = false);
+}
+
+module top_lip() {
+    if (top_lip_enable) {
+        // Front and back lips at the top of the socket.
+        translate([wall, wall, outer_h - top_lip_height])
+            cube([top_lip_depth, inner_d, top_lip_height]);
+
+        translate([outer_w - wall - top_lip_depth, wall, outer_h - top_lip_height])
+            cube([top_lip_depth, inner_d, top_lip_height]);
+    }
+}
+
+difference() {
+    union() {
+        // Main body
+        cube([outer_w, outer_d, outer_h], center = false);
+
+        // Base plate under socket for stiffness
+        translate([0, 0, -base_thickness])
+            cube([outer_w, outer_d, base_thickness], center = false);
+
+        // Mounting ears
+        if (ear_enable) {
+            translate([0, 0, -ear_thickness]) {
+                mounting_ear(1);
+                mounting_ear(-1);
+            }
+        }
+
+        top_lip();
+    }
+
+    // Main bar cavity
+    translate([wall, wall, 0])
+        cube([inner_w, inner_d, outer_h + 0.2], center = false);
+
+    // USB side notch
+    if (usb_notch_enable) {
+        if (usb_notch_side == "right") {
+            translate([outer_w - wall - 0.1, (outer_d - usb_notch_w) / 2, usb_notch_from_bottom])
+                cube([wall + 0.3, usb_notch_w, usb_notch_h], center = false);
+        } else {
+            translate([-0.2, (outer_d - usb_notch_w) / 2, usb_notch_from_bottom])
+                cube([wall + 0.3, usb_notch_w, usb_notch_h], center = false);
+        }
+    }
+
+    // Screw holes in ears
+    if (ear_enable) {
+        // Upper ear hole
+        translate([
+            outer_w / 2 + ear_len - screw_hole_edge,
+            outer_d / 2 + ear_w - screw_hole_edge,
+            -ear_thickness - 0.05
+        ]) screw_hole();
+
+        // Lower ear hole
+        translate([
+            outer_w / 2 + ear_len - screw_hole_edge,
+            -outer_d / 2 + screw_hole_edge,
+            -ear_thickness - 0.05
+        ]) screw_hole();
+    }
+}
+
+// Print orientation helper:
+// Keep the base/ears on the bed.
+// If fit is tight, increase clearance to 0.5 or 0.6.

msg.json

@@ -1,23 +0,0 @@
-{
-    "g":{ 
-        "df": {
-            "pt": "on",
-            "cl": ["#ff0000"],
-            "br": 200,
-            "n1": 10,
-            "n2": 10,
-            "n3": 10,
-            "n4": 10,
-            "n5": 10,
-            "n6": 10,
-            "dl": 100
-        },
-        "dj": {
-            "pt": "blink",
-            "cl": ["#00ff00"],
-            "dl": 500
-        }
-    },
-    "sv": true,
-    "st": 0
-}

pyproject.toml

@@ -0,0 +1,3 @@
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_endpoints_pytest.py"]

run_web.py

@@ -1,173 +0,0 @@
-#!/usr/bin/env python3
-"""
-Local development web server - imports and runs main.py with port 5000
-"""
-
-import sys
-import os
-import asyncio
-
-# Add src and lib to path
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'lib'))
-
-# Import the main module
-from src import main as main_module
-
-# Override the port in the main function
-async def run_local():
-    """Run main with port 5000 for local development."""
-    from settings import Settings
-    import gc
-    
-    # Mock MicroPython modules for local development
-    class MockMachine:
-        class WDT:
-            def __init__(self, timeout):
-                pass
-            def feed(self):
-                pass
-    import sys as sys_module
-    sys_module.modules['machine'] = MockMachine()
-    
-    class MockESPNow:
-        def __init__(self):
-            self.active_value = False
-            self.peers = []
-        def active(self, value):
-            self.active_value = value
-            print(f"[MOCK] ESPNow active: {value}")
-        def add_peer(self, peer):
-            self.peers.append(peer)
-            print(f"[MOCK] Added peer: {peer.hex() if hasattr(peer, 'hex') else peer}")
-        async def asend(self, peer, data):
-            print(f"[MOCK] Would send to {peer.hex() if hasattr(peer, 'hex') else peer}: {data}")
-    
-    class MockAIOESPNow:
-        def __init__(self):
-            pass
-        def active(self, value):
-            return MockESPNow()
-        def add_peer(self, peer):
-            pass
-    
-    class MockNetwork:
-        class WLAN:
-            def __init__(self, interface):
-                self.interface = interface
-            def active(self, value):
-                print(f"[MOCK] WLAN({self.interface}) active: {value}")
-        STA_IF = 0
-    
-    # Replace MicroPython modules with mocks
-    sys_module.modules['aioespnow'] = type('module', (), {'AIOESPNow': MockESPNow})()
-    sys_module.modules['network'] = MockNetwork()
-    
-    # Mock gc if needed
-    if not hasattr(gc, 'collect'):
-        class MockGC:
-            def collect(self):
-                pass
-        gc = MockGC()
-    
-    settings = Settings()
-    print("Starting LED Controller Web Server (Local Development)")
-    print("=" * 60)
-    
-    # Mock network
-    import network
-    network.WLAN(network.STA_IF).active(True)
-    
-    # Mock ESPNow
-    import aioespnow
-    e = aioespnow.AIOESPNow()
-    e.active(True)
-    e.add_peer(b"\xbb\xbb\xbb\xbb\xbb\xbb")
-    
-    from microdot import Microdot, send_file
-    from microdot.websocket import with_websocket
-    
-    from microdot.session import Session
-    
-    import controllers.preset as preset
-    import controllers.profile as profile
-    import controllers.group as group
-    import controllers.sequence as sequence
-    import controllers.tab as tab
-    import controllers.palette as palette
-    import controllers.scene as scene
-    import controllers.pattern as pattern
-    import controllers.settings as settings_controller
-    
-    app = Microdot()
-    
-    # Initialize sessions with a secret key from settings
-    secret_key = settings.get('session_secret_key', 'led-controller-secret-key-change-in-production')
-    Session(app, secret_key=secret_key)
-    
-    # Mount model controllers as subroutes
-    app.mount(preset.controller, '/presets')
-    app.mount(profile.controller, '/profiles')
-    app.mount(group.controller, '/groups')
-    app.mount(sequence.controller, '/sequences')
-    app.mount(tab.controller, '/tabs')
-    app.mount(palette.controller, '/palettes')
-    app.mount(scene.controller, '/scenes')
-    app.mount(pattern.controller, '/patterns')
-    app.mount(settings_controller.controller, '/settings')
-    
-    # Serve index.html at root
-    @app.route('/')
-    def index(request):
-        """Serve the main web UI."""
-        return send_file('src/templates/index.html')
-    
-    # Serve settings page
-    @app.route('/settings')
-    def settings_page(request):
-        """Serve the settings page."""
-        return send_file('src/templates/settings.html')
-    
-    # Favicon: avoid 404 in browser console (no file needed)
-    @app.route('/favicon.ico')
-    def favicon(request):
-        return '', 204
-    
-    # Static file route
-    @app.route("/static/<path:path>")
-    def static_handler(request, path):
-        """Serve static files."""
-        if '..' in path:
-            return 'Not found', 404
-        return send_file('src/static/' + path)
-    
-    @app.route('/ws')
-    @with_websocket
-    async def ws(request, ws):
-        while True:
-            data = await ws.receive()
-            if data:
-                await e.asend(b"\xbb\xbb\xbb\xbb\xbb\xbb", data)
-                print(data)
-            else:
-                break
-    
-    # Use port 5000 for local development
-    port = 5000
-    print(f"Starting server on http://0.0.0.0:{port}")
-    print(f"Open http://localhost:{port} in your browser")
-    print("=" * 60)
-    
-    try:
-        await app.start_server(host="0.0.0.0", port=port, debug=True)
-    except KeyboardInterrupt:
-        print("\nShutting down server...")
-
-if __name__ == '__main__':
-    # Change to project root
-    os.chdir(os.path.dirname(os.path.abspath(__file__)))
-    # Override settings path for local development
-    import settings as settings_module
-    settings_module.Settings.SETTINGS_FILE = os.path.join(os.getcwd(), 'settings.json')
-    
-    asyncio.run(run_local())

scripts/build_help_pdf.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# Build docs/help.pdf from docs/help.md.
+# Requires: pandoc, chromium (headless print-to-PDF).
+set -eu
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# HTML next to docs/help.md so relative image paths (e.g. images/help/*.svg) resolve.
+HTML="$ROOT/docs/.help-print.html"
+trap 'rm -f "$HTML"' EXIT
+
+pandoc "$ROOT/docs/help.md" -s \
+  --css="$ROOT/scripts/help-pdf.css" \
+  --metadata title="LED controller — user guide" \
+  -o "$HTML"
+
+chromium --headless --no-sandbox --disable-gpu \
+  --print-to-pdf="$ROOT/docs/help.pdf" \
+  "file://${HTML}"
+
+echo "Wrote $ROOT/docs/help.pdf ($(wc -c < "$ROOT/docs/help.pdf") bytes)"

scripts/dev-run.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+PORT="${PORT:-80}"
+
+# On watchfiles restarts the previous process can linger briefly.
+# Proactively terminate any listener on the target port before boot.
+pids="$(ss -ltnp "sport = :$PORT" 2>/dev/null | sed -n 's/.*pid=\([0-9]\+\).*/\1/p' | sort -u)"
+if [ -n "${pids}" ]; then
+  kill -TERM ${pids} 2>/dev/null || true
+  sleep 0.3
+fi
+
+cd "$ROOT_DIR/src"
+exec python main.py

scripts/help-pdf.css

@@ -0,0 +1,96 @@
+/* Print stylesheet for docs/help.md → PDF (Chromium headless) */
+@page {
+  margin: 18mm;
+  size: A4;
+}
+html {
+  font-size: 11pt;
+  line-height: 1.4;
+}
+body {
+  font-family: "DejaVu Sans", "Liberation Sans", Helvetica, Arial, sans-serif;
+  color: #222;
+  max-width: 100%;
+}
+h1 {
+  font-size: 1.45rem;
+  border-bottom: 2px solid #333;
+  padding-bottom: 0.25em;
+  margin-top: 0;
+}
+h2 {
+  font-size: 1.15rem;
+  margin-top: 1.25em;
+  page-break-after: avoid;
+}
+h3 {
+  font-size: 1.05rem;
+  margin-top: 1em;
+  page-break-after: avoid;
+}
+code {
+  font-family: "DejaVu Sans Mono", "Liberation Mono", Consolas, monospace;
+  font-size: 0.92em;
+  background: #f3f3f3;
+  padding: 0.1em 0.35em;
+  border-radius: 3px;
+}
+pre {
+  font-family: "DejaVu Sans Mono", "Liberation Mono", Consolas, monospace;
+  font-size: 0.88em;
+  background: #f5f5f5;
+  border: 1px solid #ddd;
+  padding: 0.65em 0.85em;
+  overflow-x: auto;
+  page-break-inside: avoid;
+}
+pre code {
+  background: none;
+  padding: 0;
+}
+table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 0.75em 0;
+  font-size: 0.95em;
+  page-break-inside: avoid;
+}
+th, td {
+  border: 1px solid #bbb;
+  padding: 6px 8px;
+  text-align: left;
+  vertical-align: top;
+}
+th {
+  background: #eee;
+}
+a {
+  color: #1a5276;
+  text-decoration: none;
+}
+hr {
+  border: none;
+  border-top: 1px solid #ccc;
+  margin: 1.25em 0;
+}
+ul, ol {
+  padding-left: 1.35em;
+}
+li {
+  margin: 0.2em 0;
+}
+
+/* Images in docs/help.md */
+img {
+  max-width: 100%;
+  height: auto;
+  page-break-inside: avoid;
+  border: 1px solid #ccc;
+  border-radius: 4px;
+}
+p.help-figure-caption {
+  font-size: 0.9em;
+  color: #555;
+  margin: 0.35em 0 1em 0;
+  line-height: 1.35;
+}

scripts/install-boot-service.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Install systemd service so LED controller starts at boot.
+# Run once: sudo scripts/install-boot-service.sh
+set -e
+cd "$(dirname "$0")/.."
+REPO="$(pwd)"
+SERVICE_NAME="led-controller.service"
+UNIT_PATH="/etc/systemd/system/$SERVICE_NAME"
+if [ ! -f "scripts/led-controller.service" ]; then
+  echo "Run this script from the repo root."
+  exit 1
+fi
+export PIPENV_VENV_IN_PROJECT="${PIPENV_VENV_IN_PROJECT:-1}"
+if command -v pipenv >/dev/null 2>&1; then
+  PY="$(command -v python3)"
+  if [ -z "$PY" ]; then
+    echo "python3 not found; install python3." >&2
+    exit 1
+  fi
+  echo "Ensuring Pipenv deps with $PY (venv in project: .venv when PIPENV_VENV_IN_PROJECT=1)…"
+  # --skip-lock: install from Pipfile only (avoids lock/Python hash mismatches on device).
+  pipenv install --quiet --skip-lock --python "$PY"
+  pipenv --venv > scripts/.led-controller-venv
+fi
+chmod +x scripts/start.sh
+sudo cp "scripts/led-controller.service" "$UNIT_PATH"
+sudo systemctl daemon-reload
+sudo systemctl enable "$SERVICE_NAME"
+echo "Installed and enabled $SERVICE_NAME"
+echo "Start now:  sudo systemctl start $SERVICE_NAME"
+echo "Status:     sudo systemctl status $SERVICE_NAME"
+echo "Logs:       journalctl -u $SERVICE_NAME -f"

scripts/led-controller.service

@@ -0,0 +1,20 @@
+[Unit]
+Description=LED Controller web server
+# Use network.target only. Ordering after network-online.target can block `systemctl start`
+# until wait-online finishes; Wi‑Fi/DHCP delays then look like a hung start job.
+After=network.target
+
+[Service]
+Type=simple
+User=pi
+WorkingDirectory=/home/pi/led-controller
+Environment=PORT=80
+Environment=PATH=/home/pi/.local/bin:/usr/local/bin:/usr/bin:/bin
+ExecStart=/bin/bash /home/pi/led-controller/scripts/start.sh
+Restart=on-failure
+RestartSec=5
+# pipenv/first bind can be slow; avoid misleading "activating" forever if misconfigured
+TimeoutStartSec=120
+
+[Install]
+WantedBy=multi-user.target

scripts/pi-eth-lan-router.sh

@@ -0,0 +1,253 @@
+#!/usr/bin/env bash
+# Configure Raspberry Pi OS: Wi-Fi client on IF_WAN (default wlan0), Ethernet IF_LAN
+# (default eth0) toward an external AP. Static LAN IP, DHCP via dnsmasq, NAT masquerade.
+#
+# Usage:
+#   sudo ./pi-eth-lan-router.sh install
+#   sudo ./pi-eth-lan-router.sh remove
+#
+# Environment overrides (optional):
+#   IF_WAN=wlan0 IF_LAN=eth0 LAN_IP=192.168.4.1 LAN_PREFIX=24 \
+#   DHCP_START=192.168.4.100 DHCP_END=192.168.4.200 \
+#   DNSMASQ_DNS=1.1.1.1,8.8.8.8 \
+#   sudo ./pi-eth-lan-router.sh install
+
+set -euo pipefail
+
+IF_WAN="${IF_WAN:-wlan0}"
+IF_LAN="${IF_LAN:-eth0}"
+LAN_IP="${LAN_IP:-192.168.4.1}"
+LAN_PREFIX="${LAN_PREFIX:-24}"
+DHCP_START="${DHCP_START:-192.168.4.100}"
+DHCP_END="${DHCP_END:-192.168.4.200}"
+# Comma-separated DNS for DHCP clients (Pi does not need to run a resolver).
+DNSMASQ_DNS="${DNSMASQ_DNS:-1.1.1.1,8.8.8.8}"
+
+NM_CON_NAME="pi-eth-lan-router"
+MARK_BEGIN="# BEGIN pi-eth-lan-router (scripts/pi-eth-lan-router.sh)"
+MARK_END="# END pi-eth-lan-router"
+SYSCTL_FILE="/etc/sysctl.d/99-pi-eth-lan-router.conf"
+DNSMASQ_SNIPPET="/etc/dnsmasq.d/pi-eth-lan-router.conf"
+NFT_SNIPPET="/etc/nftables.d/50-pi-eth-lan-router.nft"
+NFT_INCLUDE='include "/etc/nftables.d/50-pi-eth-lan-router.nft"'
+NFTABLES_CONF="/etc/nftables.conf"
+DHCPCD_CONF="/etc/dhcpcd.conf"
+
+die() { echo "error: $*" >&2; exit 1; }
+log() { echo "$*"; }
+
+need_root() {
+  [[ "${EUID:-0}" -eq 0 ]] || die "run as root (sudo)"
+}
+
+have_cmd() { command -v "$1" >/dev/null 2>&1; }
+
+apt_install() {
+  export DEBIAN_FRONTEND=noninteractive
+  apt-get update -qq
+  apt-get install -y -qq dnsmasq nftables
+}
+
+write_sysctl() {
+  cat >"$SYSCTL_FILE" <<EOF
+# Managed by scripts/pi-eth-lan-router.sh
+net.ipv4.ip_forward=1
+EOF
+  sysctl --system -q 2>/dev/null || sysctl -p "$SYSCTL_FILE" || true
+}
+
+remove_sysctl() {
+  rm -f "$SYSCTL_FILE"
+  sysctl --system -q 2>/dev/null || true
+}
+
+write_dnsmasq() {
+  local mask="255.255.255.0"
+  if [[ "$LAN_PREFIX" != "24" ]]; then
+    die "only LAN_PREFIX=24 is supported by this script (extend dnsmasq netmask manually)"
+  fi
+  cat >"$DNSMASQ_SNIPPET" <<EOF
+# Managed by scripts/pi-eth-lan-router.sh
+interface=$IF_LAN
+bind-interfaces
+dhcp-range=$DHCP_START,$DHCP_END,$mask,24h
+dhcp-option=option:router,$LAN_IP
+dhcp-option=option:dns-server,$DNSMASQ_DNS
+EOF
+}
+
+remove_dnsmasq() {
+  rm -f "$DNSMASQ_SNIPPET"
+}
+
+write_nft() {
+  mkdir -p /etc/nftables.d
+  cat >"$NFT_SNIPPET" <<EOF
+# Managed by scripts/pi-eth-lan-router.sh
+table ip pi_eth_wlan_nat {
+	chain postrouting {
+		type nat hook postrouting priority 100; policy accept;
+		oifname "$IF_WAN" masquerade
+	}
+}
+EOF
+  if [[ -f "$NFTABLES_CONF" ]] && ! grep -qF '50-pi-eth-lan-router.nft' "$NFTABLES_CONF" 2>/dev/null; then
+    printf '\n# pi-eth-lan-router\n%s\n' "$NFT_INCLUDE" >>"$NFTABLES_CONF"
+  elif [[ ! -f "$NFTABLES_CONF" ]]; then
+    log "warning: $NFTABLES_CONF missing; NAT was not added for boot persistence. Install/configure nftables, or add: $NFT_INCLUDE"
+  fi
+}
+
+remove_nft() {
+  rm -f "$NFT_SNIPPET"
+  if [[ -f "$NFTABLES_CONF" ]]; then
+    sed -i '/# pi-eth-lan-router/d;/50-pi-eth-lan-router\.nft/d' "$NFTABLES_CONF" || true
+  fi
+  nft delete table ip pi_eth_wlan_nat 2>/dev/null || true
+}
+
+apply_nft() {
+  if have_cmd nft; then
+    nft delete table ip pi_eth_wlan_nat 2>/dev/null || true
+    nft -f "$NFT_SNIPPET"
+  fi
+}
+
+configure_nm_eth() {
+  have_cmd nmcli || return 1
+  systemctl is-active --quiet NetworkManager 2>/dev/null || return 1
+
+  if nmcli -t -f NAME con show --active 2>/dev/null | grep -qxF "$NM_CON_NAME"; then
+    nmcli con down "$NM_CON_NAME" || true
+  fi
+  if nmcli -t -f NAME con show 2>/dev/null | grep -qxF "$NM_CON_NAME"; then
+    nmcli con mod "$NM_CON_NAME" \
+      connection.interface-name "$IF_LAN" \
+      ipv4.method manual \
+      ipv4.addresses "${LAN_IP}/${LAN_PREFIX}" \
+      ipv4.gateway "" \
+      ipv4.dns "" \
+      ipv4.never-default yes \
+      ipv6.method ignore
+  else
+    nmcli con add type ethernet con-name "$NM_CON_NAME" ifname "$IF_LAN" \
+      ipv4.method manual \
+      ipv4.addresses "${LAN_IP}/${LAN_PREFIX}" \
+      ipv4.gateway "" \
+      ipv4.dns "" \
+      ipv4.never-default yes \
+      ipv6.method ignore
+  fi
+  if ! nmcli con up "$NM_CON_NAME"; then
+    log "warning: could not activate '$NM_CON_NAME' (is $IF_LAN connected?); profile saved for next boot."
+  fi
+  return 0
+}
+
+remove_nm_eth() {
+  have_cmd nmcli || return 0
+  if nmcli -t -f NAME con show 2>/dev/null | grep -qxF "$NM_CON_NAME"; then
+    nmcli con delete "$NM_CON_NAME" || true
+  fi
+}
+
+configure_dhcpcd_eth() {
+  [[ -f "$DHCPCD_CONF" ]] || return 1
+  if grep -qF "$MARK_BEGIN" "$DHCPCD_CONF" 2>/dev/null; then
+    sed -i "/$MARK_BEGIN/,/$MARK_END/d" "$DHCPCD_CONF" || true
+  fi
+  {
+    echo "$MARK_BEGIN"
+    echo "interface $IF_LAN"
+    echo "static ip_address=${LAN_IP}/${LAN_PREFIX}"
+    echo "nohook wpa_supplicant"
+    echo "$MARK_END"
+  } >>"$DHCPCD_CONF"
+  systemctl restart dhcpcd 2>/dev/null || true
+  return 0
+}
+
+remove_dhcpcd_block() {
+  [[ -f "$DHCPCD_CONF" ]] || return 0
+  if grep -qF "$MARK_BEGIN" "$DHCPCD_CONF" 2>/dev/null; then
+    sed -i "/$MARK_BEGIN/,/$MARK_END/d" "$DHCPCD_CONF" || true
+    systemctl restart dhcpcd 2>/dev/null || true
+  fi
+}
+
+configure_eth_static() {
+  if configure_nm_eth; then
+    log "configured $IF_LAN via NetworkManager profile '$NM_CON_NAME'"
+    return 0
+  fi
+  if configure_dhcpcd_eth; then
+    log "configured $IF_LAN via dhcpcd ($DHCPCD_CONF)"
+    return 0
+  fi
+  die "neither NetworkManager (active) nor $DHCPCD_CONF found; set $IF_LAN to ${LAN_IP}/${LAN_PREFIX} manually"
+}
+
+remove_eth_static() {
+  remove_nm_eth
+  remove_dhcpcd_block
+}
+
+do_install() {
+  need_root
+  log "installing packages (dnsmasq, nftables)…"
+  apt_install
+
+  log "writing sysctl, dnsmasq, nftables snippets…"
+  write_sysctl
+  write_dnsmasq
+  write_nft
+
+  log "setting static IP on $IF_LAN…"
+  configure_eth_static
+
+  log "restarting dnsmasq…"
+  systemctl enable dnsmasq
+  systemctl restart dnsmasq
+
+  log "loading NAT rules and enabling nftables…"
+  apply_nft
+  systemctl enable nftables 2>/dev/null || true
+  systemctl restart nftables 2>/dev/null || true
+
+  log "done. Connect $IF_LAN to the external AP (DHCP off on the AP)."
+  log "Join Wi-Fi on $IF_WAN to the uplink network and complete any captive portal on the Pi."
+}
+
+do_remove() {
+  need_root
+  remove_eth_static
+  remove_dnsmasq
+  systemctl restart dnsmasq 2>/dev/null || true
+
+  remove_nft
+  systemctl restart nftables 2>/dev/null || true
+
+  remove_sysctl
+  sysctl -w net.ipv4.ip_forward=0 2>/dev/null || true
+
+  log "removed pi-eth-lan-router configuration snippets and NM profile '$NM_CON_NAME' (if present)."
+}
+
+usage() {
+  cat <<EOF
+Usage: sudo $0 install|remove
+
+WAN (Wi-Fi client): $IF_WAN
+LAN (Ethernet to AP): $IF_LAN
+LAN address: ${LAN_IP}/${LAN_PREFIX}
+DHCP range: $DHCP_START – $DHCP_END
+
+Override with environment variables (see script header).
+EOF
+}
+
+case "${1:-}" in
+  install) do_install ;;
+  remove) do_remove ;;
+  *) usage; exit 1 ;;
+esac

scripts/setup-port80.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Allow the app to bind to port 80 without root.
+# Run once: sudo scripts/setup-port80.sh (from repo root)
+# Or: scripts/setup-port80.sh (will prompt for sudo only for setcap)
+
+set -e
+cd "$(dirname "$0")/.."
+REPO_ROOT="$(pwd)"
+# If run under sudo, use the invoking user's pipenv so the venv is found
+if [ -n "$SUDO_USER" ]; then
+  VENV="$(sudo -u "$SUDO_USER" bash -c "cd '$REPO_ROOT' && pipenv --venv" 2>/dev/null)" || true
+else
+  VENV="$(pipenv --venv 2>/dev/null)" || true
+fi
+if [ -z "$VENV" ]; then
+  echo "Run 'pipenv install' first, then run this script again."
+  exit 1
+fi
+PYTHON="${VENV}/bin/python3"
+if [ ! -f "$PYTHON" ]; then
+  PYTHON="${VENV}/bin/python"
+fi
+if [ ! -f "$PYTHON" ]; then
+  echo "Python not found in venv: $VENV"
+  exit 1
+fi
+# Use the real binary (setcap can fail on symlinks or some filesystems)
+REAL_PYTHON="$(readlink -f "$PYTHON" 2>/dev/null)" || REAL_PYTHON="$PYTHON"
+if sudo setcap 'cap_net_bind_service=+ep' "$REAL_PYTHON" 2>/dev/null; then
+  echo "OK: port 80 enabled for $REAL_PYTHON"
+  echo "Start the app with: pipenv run run"
+else
+  echo "setcap failed on $REAL_PYTHON"
+  exit 1
+fi