JFly02
a37a3c5cbe
Darauf sitzt die erste Web-UI V1 direkt gegen diese API in [index.html](</C:/Users/janni/Documents/RFP/Infinity_Vis _Rust/web/v1/index.html>), [app.js](</C:/Users/janni/Documents/RFP/Infinity_Vis _Rust/web/v1/app.js>) und [styles.css](</C:/Users/janni/Documents/RFP/Infinity_Vis _Rust/web/v1/styles.css>). Sie enthält Pattern-/Preset-Auswahl, globale Regler, Gruppenauswahl, Übergänge, Preview, Snapshot-Anzeige und Event-Feed. Die technische Desktop-GUI bleibt bewusst die Engineering-/Diagnoseoberfläche; die kreative Web-UI baut nicht an einer Parallelarchitektur vorbei. Contract-Tests liegen in [contract.rs](</C:/Users/janni/Documents/RFP/Infinity_Vis _Rust/crates/infinity_host_api/tests/contract.rs>), und die API ist mit Beispiel-Responses in [docs/host_api.md](</C:/Users/janni/Documents/RFP/Infinity_Vis _Rust/docs/host_api.md>) dokumentiert. Zusätzlich habe ich [README.md](</C:/Users/janni/Documents/RFP/Infinity_Vis _Rust/README.md>), [docs/build_and_deploy.md](</C:/Users/janni/Documents/RFP/Infinity_Vis _Rust/docs/build_and_deploy.md>) und [docs/architecture.md](</C:/Users/janni/Documents/RFP/Infinity_Vis _Rust/docs/architecture.md>) auf den neuen Stand gebracht. Verifiziert habe ich: - `cargo check -p infinity_host_api` - `cargo test -p infinity_host_api` - `cargo test -q` Nicht verifiziert habe ich eine separate JS-Syntaxprüfung mit `node --check`, weil `node` in dieser Umgebung nicht installiert ist.
109 lines
3.7 KiB
Markdown
109 lines
3.7 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.
|
|
|
|
## Current Priority
|
|
|
|
The current delivery order is intentionally software-first:
|
|
|
|
1. host-core and shared API
|
|
2. scene, preset, group, parameter, transition, and simulation model
|
|
3. web UI as the primary creative surface
|
|
4. engineering GUI as the technical surface
|
|
5. external show-control adapters such as grandMA
|
|
6. hardware validation and real node activation later
|
|
|
|
## Layer Split
|
|
|
|
1. Control layer
|
|
- Shared host API first
|
|
- Creative web UI later
|
|
- Engineering GUI already implemented in `crates/infinity_host_ui`
|
|
- Monitoring, mapping, diagnostics, and admin
|
|
- 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.
|
|
|
|
## Shared Surface Model
|
|
|
|
Every surface must talk to the same host API:
|
|
|
|
- engineering GUI
|
|
- future creative web UI
|
|
- CLI inspection
|
|
- future grandMA adapter
|
|
|
|
The current software-first implementation uses a simulation-backed host API so looks, presets, parameters, and grouping can be developed before real node activation.
|
|
|
|
## 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. Expand creative authoring on top of the now-versioned host API and web UI
|
|
2. Keep the engineering GUI focused on mapping, diagnostics, topology, and admin
|
|
3. Implement transport adapters without coupling them to any single frontend
|
|
4. Add future external show-control bridges such as grandMA on the same API boundary
|
|
5. Keep hardware activation behind explicit later validation gates
|