# 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. ## Animation engine (Pi-side) `src/engine/` lets the Pi drive LEDs itself, in addition to the ESP32 drivers: - **Pixel generator**: runs the **unchanged** `led-driver/src/patterns/*.py` under CPython (a `utime` shim plus a NeoPixel-like buffer) with the same preset JSON the drivers get, and streams each frame to **pixel outputs**: DDP, Art-Net, sACN (E1.31), or USB-DMX (Enttec Pro / Open DMX). Configure outputs in **Outputs** (edit mode) and add an output's name to a zone's devices. - **Preset sequencer**: **Sequences** play timed chains of presets on a zone, switching both the pixel outputs and the zone's ESP32 drivers. Sequences resume after a restart. - ESP32 firmware is unchanged; drivers still get presets + `select`. CLI (run from `src/`): ```bash python -m engine.cli --output "ddp://192.168.1.60?pixels=300" --test python -m engine.cli --output "artnet://192.168.1.61?universe=0&pixels=170" --preset 16 python -m engine.cli --pattern rainbow --n1 2 --leds 60 # terminal preview ``` Tests: `pipenv run pytest tests/engine_tests`.