86 lines
2.8 KiB
Markdown
86 lines
2.8 KiB
Markdown
# Architecture
|
|
|
|
## Goal
|
|
|
|
Build a live-capable LED control platform that keeps realtime output deterministic while letting operators change scenes, brightness, tests, and presets without UI jitter leaking into the hot path.
|
|
|
|
## Layer Split
|
|
|
|
1. Control layer
|
|
- Operator workflow
|
|
- Presets and topology editing
|
|
- Monitoring and diagnostics
|
|
- Never the timing master for LED output
|
|
2. Realtime engine
|
|
- Owns the monotonic clock
|
|
- Computes scene state, transitions, and dirty regions
|
|
- Produces transport-ready commands or pixel frames
|
|
3. Transport and node layer
|
|
- Discovery, heartbeat, config sync, sequencing, and recovery
|
|
- Control protocol and realtime protocol stay separate
|
|
- Latest realtime state wins, stale frames may be dropped
|
|
4. ESP32 firmware
|
|
- Receives commands
|
|
- Maintains local buffers
|
|
- Drives three independent outputs per node
|
|
- Handles watchdog and reconnect logic locally
|
|
|
|
## Runtime Model
|
|
|
|
- Logic tick target: 120 Hz
|
|
- Frame synthesis target: 60 Hz
|
|
- Network send target: 40-60 Hz, profile dependent
|
|
- Preview target: 10-15 Hz
|
|
|
|
Preview and telemetry are explicitly degradable. Realtime output is not.
|
|
|
|
## Modes
|
|
|
|
### Distributed Scene Mode
|
|
|
|
- Default operating mode
|
|
- Host sends scene parameters, time basis, seed, palette, and transitions
|
|
- Nodes render locally for low bandwidth and better resilience
|
|
|
|
### Frame Streaming Mode
|
|
|
|
- Used for mapping tests, debugging, and effects that cannot run node-local
|
|
- Host sends explicit output frames
|
|
- Kept logically separate so it does not contaminate the primary scene pipeline
|
|
|
|
## Mapping Model
|
|
|
|
The project configuration separates mapping into three layers:
|
|
|
|
1. Hardware mapping
|
|
- Node ID
|
|
- Top, middle, bottom output
|
|
- Physical output label
|
|
- Driver channel reference
|
|
- LED count, direction, color order, enable flag
|
|
2. Layout mapping
|
|
- Optional row and column placement
|
|
- Optional preview transforms only
|
|
3. Group mapping
|
|
- Explicit groups for artistic control and fast operator access
|
|
|
|
The current example config intentionally keeps layout mapping empty because the old XML is only a spatial reference and the final node-to-room placement must still be confirmed on real hardware.
|
|
|
|
## Validation Gates
|
|
|
|
The codebase deliberately blocks activation when these remain unresolved:
|
|
|
|
- `UART 6`, `UART 5`, `UART 4` still marked as `pending_validation`
|
|
- output validation state is not `validated`
|
|
- LED count deviates from 106
|
|
- node outputs are missing top, middle, or bottom
|
|
- driver references are ambiguous or duplicated per node
|
|
|
|
## Planned Next Steps
|
|
|
|
1. Add the actual UI adapter on top of `infinity_host`
|
|
2. Implement UDP transport with separate control and realtime sockets
|
|
3. Connect firmware driver backends after hardware validation
|
|
4. Add deterministic effect registry shared between host planning and firmware capability negotiation
|
|
|