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.

1.5 KiB Raw Blame History