====== er-lights ======

Dynamic lighting control system for escape rooms, combining a dedicated hardware controller with a PC application. The controller drives addressable LED strips and DMX fixtures in real time over Ethernet. The PC application generates animations and provides an HTTP API for control from Node-RED.

**Status:** Hardware controller — working prototype. PC application — in development (animation engine functional, HTTP API in progress).

===== System Overview =====

<code>
  Main PC                          er-lights controller
  ┌────────────────────┐                ┌───────────────────────────┐
  │ er-lights app      │   Ethernet     │                           │
  │                    │ ──────────────→│  LED CH 1 ──→ [LED strip] │
  │ - Animations       │   UDP 5568     │  LED CH 2 ──→ [LED strip] │
  │ - HTTP API         │                │  LED CH 3 ──→ [LED strip] │
  │ - Node-RED control │                │                           │
  └────────────────────┘                │  DMX A ────→ [fixtures]   │
                                        │  DMX B ────→ [fixtures]   │
                                        └───────────────────────────┘
</code>

===== Hardware Controller =====

==== LED Outputs ====

^ Parameter ^ Value ^
| Channels | 4 independent outputs |
| LEDs per channel | Up to 480 (5 m at 96 LED/m) |
| Total capacity | Up to **1,920 individually addressable RGB LEDs** |
| Supported LED strips | WS2812B, WS2811 |
| Strip voltages | 5V, 12V, or 24V — each channel independent |
| Color depth | 24-bit RGB (8 bits per color) |
| Refresh rate | Up to 60 Hz |

Each LED output has:
  * 3.3V → 5V level conversion for reliable signal integrity
  * Short-circuit protection on the DATA line

==== DMX Outputs ====

^ Parameter ^ Value ^
| Universes | 2 independent outputs |
| Channels per universe | Up to 512 |
| Total DMX channels | **1,024** |
| Isolation | Galvanic isolation on each output |
| Driver | Industrial-grade RS-485 transceivers |

==== Network ====

^ Parameter ^ Value ^
| Interface | 100 Mbit Ethernet |
| Protocol | UDP, port 5568 |

A dedicated network segment or VLAN is recommended for latency-sensitive installations with high LED counts.

===== Protocols =====

The controller accepts two protocols on the same UDP port. The format is auto-detected from the packet header.

==== ERLED480 (Custom) ====

Lightweight protocol optimized for LED data. Minimal overhead — a full 480-LED frame is only 1,450 bytes.

Channel mapping: Channels 1–4 → LED outputs.

==== sACN / E1.31 (Industry Standard) ====

Standard DMX-over-Ethernet protocol for compatibility with third-party lighting software.

**Universe mapping:**
^ Universe ^ Output ^
| 1–4 | LED channels (RGB triplets, up to 170 LEDs per universe) |
| 5 | DMX Output A (512 channels) |
| 6 | DMX Output B (512 channels) |

===== PC Application =====

==== Animation Engine ====

The PC application runs on the Main PC (or a dedicated machine over LAN) alongside Node-RED. It generates lighting data and transmits it to the hardware controller over Ethernet.

**Capabilities:**
  * Optimized for low-latency, real-time rendering
  * Temporal smoothing to prevent flicker
  * Per-channel color calibration (R/G/B gain adjustment)
  * Built-in animations (color cycling, chase, fill, procedural effects)
  * Custom animations supported

==== Segment Mapping ====

A physical LED strip can be divided into multiple independent **segments**, each running its own animation.

==== DMX Control ====

The software emulates a DMX console, providing full channel-level control. DMX fixtures are configured with named parameters (dimmer, color, pan, tilt, etc.) for intuitive control from Node-RED.

==== HTTP API (Planned) ====

  * ''POST /api/config'' — load scene configuration
  * ''POST /api/led/segment'' — set segment state (color, gradient, animation)
  * ''POST /api/led/frame'' — direct frame update
  * ''POST /api/dmx/fixture'' — set DMX fixture parameters
  * ''POST /api/dmx/raw'' — raw DMX channel control

===== Specifications Summary =====

^ Feature ^ Value ^
| LED outputs | 4 channels, up to 480 RGB LEDs each (1,920 total) |
| DMX outputs | 2 universes, 512 channels each (1,024 total) |
| LED strips | WS2812B, WS2811 (5V, 12V, or 24V) |
| DMX isolation | Galvanic, per output |
| Network | 100 Mbit Ethernet, UDP port 5568 |
| Protocols | ERLED480 (custom) + sACN/E1.31 (standard) |
| Segment mapping | Independent zones on a single strip |
| Animation engine | Real-time, low-latency, flicker-free |