68 lines
1.5 KiB
Markdown
68 lines
1.5 KiB
Markdown
# Protocol
|
|
|
|
## Design Rules
|
|
|
|
- Separate control traffic from realtime traffic
|
|
- Version every envelope
|
|
- Keep realtime messages disposable
|
|
- Prefer idempotent control commands
|
|
- Let nodes recover independently after packet loss or reconnect
|
|
|
|
## Control Protocol
|
|
|
|
Purpose:
|
|
|
|
- Discovery
|
|
- Heartbeat
|
|
- Config sync
|
|
- Preset recall
|
|
- Panic and blackout
|
|
- Telemetry
|
|
|
|
Current envelope model:
|
|
|
|
- `protocol_version`
|
|
- `sequence`
|
|
- `sent_at_millis`
|
|
- `message`
|
|
|
|
Current control messages:
|
|
|
|
- `discovery_hello`
|
|
- `discovery_ack`
|
|
- `config_sync`
|
|
- `heartbeat_request`
|
|
- `heartbeat`
|
|
- `preset_recall`
|
|
- `blackout`
|
|
|
|
`config_sync` carries the authoritative per-node hardware assignment so the node can reject invalid activation before the first frame.
|
|
|
|
## Realtime Protocol
|
|
|
|
Purpose:
|
|
|
|
- Scene parameters for distributed rendering
|
|
- Explicit pixel frames for frame streaming mode
|
|
- Resync requests
|
|
|
|
Current realtime messages:
|
|
|
|
- `scene_parameters`
|
|
- `pixel_frame`
|
|
- `resync_request`
|
|
|
|
## Delivery Semantics
|
|
|
|
- Control messages must be small and replay-safe where possible
|
|
- Realtime messages use latest-state-wins semantics
|
|
- Nodes may drop stale realtime frames rather than replay them
|
|
- A reconnecting node must request or receive a clean config sync before resuming output
|
|
|
|
## DDP Compatibility
|
|
|
|
DDP is treated as an optional compatibility shell for frame streaming mode only.
|
|
|
|
The internal model is intentionally broader than DDP because the preferred operating path is distributed scene mode with time-based parameters and node-local rendering.
|
|
|