From 7336c7fb2273fd6941e71c633f2dd73b11113d8b Mon Sep 17 00:00:00 2001 From: jimmy Date: Tue, 27 Oct 2026 02:02:13 +1300 Subject: [PATCH] docs: document engine, outputs, sequences, brightness and search; update spec Co-Authored-By: Claude Sonnet 5.5 --- README.md | 7 +++++++ docs/SPECIFICATION.md | 49 ++++++++++++++++++++++++++++++++++++------- docs/help.md | 23 ++++++++++++++++---- 3 files changed, 68 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 0d93445..bad815e 100644 --- a/README.md +++ b/README.md @@ -34,9 +34,16 @@ LED controller web app for managing profiles, **zones**, presets, and colour pal - 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. +## Brightness and search + +- The header **Brightness** slider sets the server-wide `global_brightness` (saved via `PUT /settings`, broadcast to connected drivers, and re-sent when a Wi-Fi driver reconnects). +- The Devices, Zones and Presets modals have a client-side search filter. + ## API docs - Main API reference: `docs/API.md` +- User guide: `docs/help.md` +- Full specification: `docs/SPECIFICATION.md` ## Driver pattern modules diff --git a/docs/SPECIFICATION.md b/docs/SPECIFICATION.md index e522513..67b878a 100644 --- a/docs/SPECIFICATION.md +++ b/docs/SPECIFICATION.md @@ -1,13 +1,14 @@ # LED Driver System - Specification Document -**Version:** 1.0 -**Date:** December 2025 +**Version:** 1.1 +**Date:** October 2026 **Status:** Draft ## Table of Contents 1. [Overview](#overview) 2. [System Architecture](#system-architecture) + - [Raspberry Pi Controller and Animation Engine](#raspberry-pi-controller-and-animation-engine) 3. [User Interface Specifications](#user-interface-specifications) 4. [Feature Specifications](#feature-specifications) 5. [Preset System](#preset-system) @@ -54,6 +55,11 @@ The LED Driver system is a MicroPython-based application for controlling LED str - Persistent settings storage (usqlite database) - Web-based configuration interface (Microdot web server) - SQLite database for presets and event logging +- **Raspberry Pi controller** (`src/`): Microdot web app with JSON-file storage (`db/*.json`) managing profiles, zones, presets, palettes, scenes, sequences and outputs +- **Pi-side animation engine** (`src/engine/`): renders the unchanged driver patterns on the Pi and streams pixels over DDP, Art-Net, sACN (E1.31) or USB-DMX +- **Preset sequencer**: timed preset chains per zone, resumed after restart +- Server-wide global brightness (0-255) pushed to drivers, including on Wi-Fi reconnect +- Search filter in the Devices, Zones and Presets lists --- @@ -225,6 +231,29 @@ The LED Driver system uses a master/slave architecture where one device acts as --- +## Raspberry Pi Controller and Animation Engine + +The current deployment adds a Raspberry Pi running the web app (`src/main.py`, Microdot on CPython). It is the authoritative store and UI host; ESP32 firmware is unchanged. Full route detail is in `docs/API.md`. + +**Outbound paths** +- Serial → ESP-NOW bridge (JSON lines over UART). +- Wi-Fi drivers: TCP JSON lines (port 8765 on the Pi; drivers discover the Pi via UDP 8766 broadcast). +- Pixel outputs rendered by the Pi engine (below). + +**Data model (`db/*.json`):** profile, zone, preset, palette, pattern, device, scene, sequence, output. A zone's `names` list holds ESP32 device names and/or output names. + +### Animation Engine (`src/engine/`) + +- **Pixel generator:** loads `led-driver/src/patterns/*.py` unmodified under CPython (`utime` shim plus a NeoPixel-like buffer) and runs one render thread per zone from the same preset JSON the drivers receive. Static frames are re-sent as keepalive. +- **Output drivers:** DDP (UDP 4048), Art-Net (ArtDMX/ArtSync, UDP 6454), sACN/E1.31 (UDP 5568, multicast or unicast), USB-DMX (Enttec DMX USB Pro or Open DMX). 170 RGB pixels per universe, consecutive universes for longer strips. A preset output for our ESP32 drivers (`outputs/driver.py`) reuses the existing preset + `select` path. +- **Output record** (`db/output.json`): `name`, `protocol`, `host`, `port`, `universe`, `serial_port`, `dmx_mode`, `channel`, `pixel_count`, `pixel_offset`, `color_order`, `reverse`, `brightness` (0-255, multiplied by global brightness), `fps` (default 40), `enabled`. CRUD and a test pattern (R, G, B, W, off) at `/outputs`. +- **Zone playback:** `POST /zones//play` renders a preset on every target and sends `select` to ESP32 drivers; `POST /zones//stop` blanks pixel outputs. `GET /zones/engine/status` reports per-zone and per-output counters. +- **Sequencer:** a sequence is `{name, zone_id, loop, repeat_count, steps: [{preset_id, duration_s}], active}`. `duration_s` is clamped to 0.5-600 s (default 5); steps are hard cuts; `repeat_count` of 0 loops forever. Deadline-based scheduling, `active` sequences resume after restart, manual preset selection on a zone stops its sequence. Legacy records (`group_name`, `presets`, `sequence_duration` ms) are migrated on load. Scenes start/stop the sequences they list (`/scenes//play`, `/stop`). +- **CLI:** `python -m engine.cli --output "ddp://host?pixels=300" --test | --preset N | --pattern NAME` (terminal preview when no output is given). +- **UI:** Outputs and Sequences modals (edit mode), preset tiles drive pixel outputs, header brightness slider, list search filters. + +--- + ## User Interface Specifications ### 1. Dashboard (Main Control Panel) @@ -1575,11 +1604,13 @@ peak_mem = usqlite.mem_peak() ### Flow 8: Sequence Between Presets -1. Scene activated with group having multiple presets -2. Master applies first preset to itself (if in group), sends to slaves -3. After duration expires, master transitions to next preset with fade effect -4. Process repeats for all presets, loops if enabled -5. Continues until scene changes or manual stop +*(Implemented by the Pi-side sequencer; see Animation Engine.)* + +1. User plays a sequence (or a scene that lists it) on a zone +2. Pi applies the first step: renders it to the zone's pixel outputs and sends the preset + `select` to its ESP32 drivers +3. After `duration_s` expires, the sequencer hard-cuts to the next step +4. Process repeats for all steps; loops forever or for `repeat_count` passes +5. Continues until stopped, the zone is played manually, or the app restarts (active sequences then resume) --- @@ -1649,6 +1680,10 @@ peak_mem = usqlite.mem_peak() - Any length (1-1000 LEDs supported) - 5V power supply (external) +**Raspberry Pi (controller):** +- Python 3.x, runs the web app and animation engine +- Optional: Wi-Fi/Ethernet to DDP, Art-Net or sACN fixtures; USB-DMX adapter (Enttec DMX USB Pro / Open DMX) + **Host Computer:** - Python 3.x - pipenv for dependency management diff --git a/docs/help.md b/docs/help.md index 5e604db..445ddbd 100644 --- a/docs/help.md +++ b/docs/help.md @@ -19,7 +19,7 @@ The header has a mode toggle (desktop and mobile menu). The **label on the butto | 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. | +| **Edit mode** | Full setup: zones, presets, patterns, outputs, sequences, 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. @@ -30,7 +30,8 @@ The header has a mode toggle (desktop and mobile menu). The **label on the butto - **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. +- **Brightness slider** (header, and in the mobile menu): adjusts the **global** brightness (0–255) sent to devices (`b` in the driver message), with a short debounce so small drags do not flood the link. The level is stored on the server (`global_brightness`) and re-sent to Wi-Fi drivers when they reconnect; the slider position is also remembered in your browser. +- **Search**: the Devices, Zones and Presets lists have a search box that hides non-matching rows as you type. It clears when you reopen the list or press **Esc**. --- @@ -41,7 +42,7 @@ The header has a mode toggle (desktop and mobile menu). The **label on the butto - **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) +![Schematic: zone title, brightness slider, and a row of preset tiles; Edit mode adds an Edit control and drag handles for reordering.](images/help/tab-preset-strip.svg) *The slider controls global brightness for the zone’s devices. Click the coloured area of a tile to select that preset.* @@ -74,6 +75,20 @@ The **Presets** header button (Edit mode) opens a **profile-wide** list: **Add** --- +## Outputs (Edit mode) + +Besides the ESP32 drivers, the Pi can render patterns itself and stream pixels to network or DMX fixtures. **Outputs** lists these fixtures; each has a **name**, a **protocol** (DDP, Art-Net, sACN/E1.31 or USB-DMX), its address (host/port, universe or serial port), pixel count and offset, colour order, brightness and frame rate. Use **Test** on an output to flash red, green, blue and white, then black. + +To drive an output from a zone, add the output's **name** to the zone's device list (the same list used for ESP32 device names). Clicking a preset tile then renders it on the Pi for those outputs and still sends `select` to any ESP32 drivers in the zone. + +--- + +## Sequences (Edit mode) + +**Sequences** are timed chains of presets that play on one zone. Each step is a preset plus a duration (0.5–600 s); steps switch with hard cuts. Choose whether the sequence **loops** (and how many passes, 0 = forever), then **Play** or **Stop** it. Picking a preset by hand on that zone stops its sequence. Running sequences resume after the app restarts, and a **scene** can start every sequence it lists. + +--- + ## 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. @@ -100,7 +115,7 @@ The **Patterns** dialog (Edit mode) lists pattern names and typical **delay** ra ## Mobile layout -On narrow screens, use **Menu** to reach the same actions as the desktop header (Profiles, Zones, Presets, Help, mode toggle, etc.). +On narrow screens, use **Menu** to reach the same actions as the desktop header (Profiles, Zones, Presets, Outputs, Sequences, Help, mode toggle, brightness, etc.). ![Schematic: narrow layout with Menu and the same header actions in a dropdown.](images/help/mobile-menu.svg)