UDP Cue Command Reference

NORTHSTARSHOW SYSTEMS

UDP Cue Command Reference

Wire protocol between HelmOS and Polaris nodes

Port

HelmOS listens on UDP 8888 (HELMOS_UDP_PORT). Polaris nodes also listen on UDP 8888. Both send and receive JSON payloads with a single object per packet.

Inbound — Node → HelmOS

Heartbeat

{"type":"heartbeat","node_id":"uuid","uptime":1234,"fw_version":"1.0.0"}

Sent every 5 seconds. HelmOS uses the heartbeat to track node liveness and current firmware version.

Input Event (GPIO / sensor)

{"type":"input","node_id":"uuid","index":2,"name":"Foyer PIR","pin":3,"value":1}

Sent when a configured input pin transitions to its trigger edge.

Bridge Input Event

{"type":"bridge-input","node_id":"bridge-uuid","role":"show-start","name":"Show Start","pin":2,"value":1}

Sent by the Bridge node when a button is pressed or the key switch changes state.

Outbound — HelmOS → Node

Fire

{"cue":"fire","channel":3,"value":1}

Set the specified output channel to value. Channel is 1-indexed.

Release

{"cue":"release","channel":3}

Return the channel to its default state.

Pulse

{"cue":"pulse","channel":3,"duration_ms":200}

Drive the channel active for duration_ms, then release.

Play (audio nodes)

{"cue":"play","channel":1}

Trigger track number channel on the audio node.

Stop All

{"cue":"stop"}

Set every output on this node to its default state.

Reliability

UDP is connectionless. Northstar accepts the possibility of packet loss in exchange for the latency benefit of UDP over TCP. Critical state (heartbeat, registration) is acknowledged at the application layer; loss of a single show command is rare and easily compensated by re-issuing or by the next heartbeat cycle.

Related Documents

• NSSS-DOC-0051Polaris GPIO Datasheet
• NSSS-DOC-0091HelmOS HTTP API Reference

Revision History