led-controller

LED controller web app for managing profiles, zones, presets, and colour palettes, and sending commands to LED devices over ESP-NOW (binary wire format).

• Bridge ESP32: runs a WebSocket server; the Pi connects as client (bridge_ws_url in settings.json, e.g. ws://192.168.4.1/ws).
• LED drivers: announce on boot via ESP-NOW broadcast; the controller registers them and pushes group membership.
• Architecture (diagrams): docs/espnow-architecture.md
• Wire format (byte layouts): docs/espnow-binary-protocol.md (≤250 bytes per frame, no JSON on the wire)

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.