The Node.js service that turns a Helm PC into a show controller. State machine, scheduler, REST + WebSocket API, Bridge driver, Cuemaster host. Hot-reloads nodes.json without restarting.
[helmos] starting helmos 1.0.0 [helmos.config] loaded nodes.json — 12 nodes, 64 channels [helmos.bridge] opened serial COM3 @ 115200 [helmos.bridge] handshake — HELLO:BRIDGE:1.0.0 [helmos.health] all 12 nodes online [helmos.api] listening 0.0.0.0:3000 [helmos.show] state: IDLE [helmos.bridge] BTN:START [helmos.show] IDLE → RUNNING [helmos.sequence] firing "intro" — 14 steps [helmos.trigger] fired node=001 ch=1 latencyMs=23 [helmos.trigger] fired node=001 ch=2 latencyMs=21 [helmos.trigger] fired node=002 ch=1 latencyMs=27
HelmOS sits in the middle: Bridge buttons come in over USB serial, Polaris nodes go out over HTTP, Cuemaster connects over WebSocket, and a single nodes.json defines the whole show. Every Northstar venue runs the same runtime.
IDLE → RUNNING → STOPPED. RESET returns to IDLE from any state. MAINT and ERROR are first-class states. Transitions broadcast over WebSocket.
Cron for time-of-day, interval for repeating, manual for on-demand. Respects venue timezone. Skips when maintenance key is engaged.
Absolute-timing steps. Parallel fan-out. Group expansion. Loop support. Sub-millisecond dispatch precision.
5-second health check cycle. Tracks ONLINE / SLOW / OFFLINE per node. RSSI reported per check. Status transitions emit WebSocket events.
POST /api/config with a new nodes.json. Schema validates. In-flight sequences finish. New config applies. Zero downtime.
Adjust cooldowns, schedules, IPs at runtime. Persisted to runtime-overrides.json. Survive restart. Cleared explicitly or via Cuemaster.
HelmOS exposes a small, documented JSON API that anything can drive. Cuemaster uses it. Compose can write to it. Third-party systems (LX consoles, ticketing kiosks, motion control) use it to integrate.
| GET /api/status | System summary: show state, node count, bridge, version |
|---|---|
| GET /api/nodes | Every node with live status, RSSI, uptime |
| GET /api/trigger | Fire one channel on one node |
| POST /api/show/start | Begin show — runs bootSequence, transitions to RUNNING |
| POST /api/show/stop | Halt show, transition to STOPPED |
| POST /api/show/reset | Return to IDLE, clear stuck channels |
| GET /api/config | Return currently loaded nodes.json |
| POST /api/config | Upload and hot-reload nodes.json (with ?dryRun=true) |
| GET / POST / DELETE /api/overrides | List, set, clear runtime overrides |
| GET /api/schedule | Schedule list with next-fire times |
| POST /api/schedule/fire | Force-fire a schedule immediately |
| GET /api/logs | Tail log lines by level / time / count |
| WS /ws | Live event stream: show:state, trigger:fired, node:status, error |
HelmOS is registered with NSSM as a Windows service. It auto-starts at boot before any user is logged in. If the Node.js process crashes, NSSM restarts it within 2 seconds. If it crashes repeatedly, NSSM throttles to prevent a tight loop.
Stdout and stderr are captured to rotating log files. The application logger writes a separate helmos.log with structured messages, and an append-only triggers.log records every effect fire for forensic reconstruction after an incident.
HelmOS, auto-start, auto-restartC:\ProgramData\Northstar\helmos ┌──────────────────────┐
│ BRIDGE (USB) │
└──────────┬───────────┘
│ serial
▼
┌───────────────────────┐
│ HelmOS │
│ ┌──────┐ ┌────────┐ │
│ │state │ │schedule│ │
│ └──┬───┘ └───┬────┘ │
│ │ │ │
│ ┌──▼─────────▼────┐ │
│ │ sequence engine │ │
│ └────┬────────┬───┘ │
└───────┼────────┼──────┘
HTTP │ │ WebSocket
▼ ▼
┌──────────┐ ┌─────────┐
│ POLARIS │ │ Cuemstr │
└──────────┘ └─────────┘
NSSM brings HelmOS back within 5 seconds of any unexpected exit. Show state is reconstructed from nodes.json + overrides.
Per-trigger HTTP timeout 1.5 s. Failed triggers do not halt the show. Cuemaster shows a slow-node warning instead of an outage.
USB disconnect during show? Show keeps running. HelmOS retries every 2 s. When Bridge replugs, LED state restores within 10 s.
Every trigger is appended to triggers.log with timestamp, node, channel, source, latency. Hours of post-incident clarity.
Download the runtime, set HELMOS_MOCK=true, and run a full Northstar stack on your laptop without any hardware. Five minutes to a working Cuemaster dashboard.