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
+42
-7
@@ -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/<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
|
||||
|
||||
### 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
|
||||
|
||||
Reference in new issue
Block a user