WebSocket Protocol Reference

NORTHSTARSHOW SYSTEMS

WebSocket Protocol Reference

Real-time messaging between HelmOS and clients

Document Number	Revision	Date	Platform Version
NSSS-DOC-0092	A	2026-05-20	1.0

Endpoint

ws://<helm>:3000/ws — same TCP port as HTTP. No subprotocol negotiation; JSON-only messages.

Hello Snapshot

On connect, HelmOS immediately sends one snapshot message:

{
  "t": "hello",
  "state": {
    "project": { /* full ComposeProject or null */ },
    "nodes": [ /* RegisteredNode[] */ ],
    "activity": [ /* last 50 ActivityEntry[] */ ],
    "activeRuns": [ /* current cue runs */ ],
    "maintenance": false,
    "firmwareJobs": [ /* active OTA jobs */ ],
    "licensed": true
  }
}

Server → Client Messages

t	Payload	Meaning
hello	state snapshot	Once per connection on open
project	{ project }	A new .nsss.compose was deployed
node-registered	{ node }	A Polaris node joined for the first time
node-updated	{ node }	Existing node state changed (heartbeat, fw_version)
cue-started	{ run }	A cue script began executing
cue-finished	{ run, ok }	A cue script ended
channel	{ nodeId, channelId, value }	A specific channel state changed
activity	{ entry }	New activity log entry
maintenance	{ active }	Maintenance toggled
firmware-job	{ job }	OTA progress event
license	{ activated, customer, expires }	License status changed
cuemaster-out	{ outputKey, payload, nodeId }	Cuemaster output event

Client → Server Messages

t	Payload	Effect
fire-cue	{ cueId, by? }	Manually fire a cue (gates apply)
cuemaster-event	{ nodeId, eventKey }	Fire event-cuemaster hats
stop-all	{ }	Abort everything + broadcast STOP
enter-maint	{ }	Force maintenance on (admin)
exit-maint	{ }	Force maintenance off

Reconnection

Cuemaster maintains its WebSocket connection indefinitely. On close it retries with a 1.5-second back-off. The first message after each successful reconnect is a fresh hello with a complete state snapshot.

NSSS-DOC-0091HelmOS HTTP API Reference

Revision History

Revision	Date	Description
A	2026-05-20	Initial publication