docs: document engine, outputs, sequences, brightness and search; update spec
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
3a7723c586
commit
7336c7fb22
3 files changed
+68
-11
No files matched your search
@@ -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.
|
- 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.
|
- 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
|
## API docs
|
||||||
|
|
||||||
- Main API reference: `docs/API.md`
|
- Main API reference: `docs/API.md`
|
||||||
|
- User guide: `docs/help.md`
|
||||||
|
- Full specification: `docs/SPECIFICATION.md`
|
||||||
|
|
||||||
## Driver pattern modules
|
## Driver pattern modules
|
||||||
|
|
||||||
|
|||||||
+42
-7
@@ -1,13 +1,14 @@
|
|||||||
# LED Driver System - Specification Document
|
# LED Driver System - Specification Document
|
||||||
|
|
||||||
**Version:** 1.0
|
**Version:** 1.1
|
||||||
**Date:** December 2025
|
**Date:** October 2026
|
||||||
**Status:** Draft
|
**Status:** Draft
|
||||||
|
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
|
|
||||||
1. [Overview](#overview)
|
1. [Overview](#overview)
|
||||||
2. [System Architecture](#system-architecture)
|
2. [System Architecture](#system-architecture)
|
||||||
|
- [Raspberry Pi Controller and Animation Engine](#raspberry-pi-controller-and-animation-engine)
|
||||||
3. [User Interface Specifications](#user-interface-specifications)
|
3. [User Interface Specifications](#user-interface-specifications)
|
||||||
4. [Feature Specifications](#feature-specifications)
|
4. [Feature Specifications](#feature-specifications)
|
||||||
5. [Preset System](#preset-system)
|
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)
|
- Persistent settings storage (usqlite database)
|
||||||
- Web-based configuration interface (Microdot web server)
|
- Web-based configuration interface (Microdot web server)
|
||||||
- SQLite database for presets and event logging
|
- 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/<id>/play` renders a preset on every target and sends `select` to ESP32 drivers; `POST /zones/<id>/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/<id>/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
|
## User Interface Specifications
|
||||||
|
|
||||||
### 1. Dashboard (Main Control Panel)
|
### 1. Dashboard (Main Control Panel)
|
||||||
@@ -1575,11 +1604,13 @@ peak_mem = usqlite.mem_peak()
|
|||||||
|
|
||||||
### Flow 8: Sequence Between Presets
|
### Flow 8: Sequence Between Presets
|
||||||
|
|
||||||
1. Scene activated with group having multiple presets
|
*(Implemented by the Pi-side sequencer; see Animation Engine.)*
|
||||||
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
|
1. User plays a sequence (or a scene that lists it) on a zone
|
||||||
4. Process repeats for all presets, loops if enabled
|
2. Pi applies the first step: renders it to the zone's pixel outputs and sends the preset + `select` to its ESP32 drivers
|
||||||
5. Continues until scene changes or manual stop
|
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)
|
- Any length (1-1000 LEDs supported)
|
||||||
- 5V power supply (external)
|
- 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:**
|
**Host Computer:**
|
||||||
- Python 3.x
|
- Python 3.x
|
||||||
- pipenv for dependency management
|
- pipenv for dependency management
|
||||||
|
|||||||
+19
-4
@@ -19,7 +19,7 @@ The header has a mode toggle (desktop and mobile menu). The **label on the butto
|
|||||||
| Mode | Purpose |
|
| Mode | Purpose |
|
||||||
|------|--------|
|
|------|--------|
|
||||||
| **Run mode** | Day-to-day control: choose a zone, tap presets, apply profiles. Management buttons are hidden. |
|
| **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.
|
**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.
|
- **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.
|
- **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).
|
- **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).
|
- **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.
|
- **Drag and drop** tiles to reorder them; order is saved for that zone.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
*The slider controls global brightness for the zone’s devices. Click the coloured area of a tile to select that preset.*
|
*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 (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.
|
**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
|
## 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.).
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user