Bridge Serial Protocol
NORTHSTAR SHOW SYSTEMS
Bridge Serial Protocol
USB serial command reference for the operator panel
v1.0 — May 2026
Bridge Serial Protocol
The Bridge is an Arduino UNO R4 WiFi that serves as the physical operator panel. It connects to Helm via USB CDC serial at 115200 baud, newline-delimited ASCII. No external Arduino libraries are required.
Physical connections
The Bridge sketch uses the following pin assignments by default:
| Pin | Direction | Function |
|---|---|---|
| D2 | Input | Show Start button |
| D3 | Input | Show Stop button |
| D4 | Input | Show Reset button |
| D5 | Input | Maintenance key switch (latching) |
| D6 | — | Reserved / unused |
| D7 | Input | Server Reset button (requires 3-second hold) |
| D8 | Output | Channel 1 — Show Start LED |
| D9 | Output | Channel 2 — Show Stop LED |
| D10 | Output | Channel 3 — Show Reset LED (software flash at 2 Hz) |
| D11 | Output | Channel 4 — Maintenance Mode LED |
| D12 | Output | Channel 5 — Server Running LED (slow blink at 0.5 Hz on heartbeat loss) |
| D13 | Output | Channel 6 — PC Ping OK LED (200 ms pulse per PONG) |
LEDs are relay-driven (active-HIGH by default). Set ACTIVE_HIGH to 0 at the top of the sketch if the relay board is active-LOW. No PWM dimming is available through relays — the server-lost state is rendered as a slow blink, not a brightness change.
Bridge to Helm messages
The Bridge sends these ASCII commands to HelmOS, one per line:
| Command | Trigger | Description |
|---|---|---|
| SHOW_START | D2 button press | Request transition from STOPPED to RUNNING. Blocked if maintenance is active. |
| SHOW_STOP | D3 button press | Request transition from RUNNING to STOPPED. Cancels all running sequences. Always works (panic stop). |
| SHOW_RESET | D4 button press | Request transition to RESETTING. Cancels all sequences, 5-second yellow LED flash window. Always works. |
| MAINT_ON | D5 key switch ON | Enable maintenance mode. Blocks SHOW_START, manual triggers, and new schedule-fired sequences. |
| MAINT_OFF | D5 key switch OFF | Disable maintenance mode. Resumes normal operation. |
| SERVER_RESET | D7 held 3 seconds | Graceful in-process restart: abort sequences, close WS clients (code 1012), reload nodes.json, re-open serial. Same PID. |
| PING | Every 10 seconds | Keepalive. HelmOS must respond with PONG within 1 second. |
Helm to Bridge messages
HelmOS sends these commands to control Bridge LEDs and confirm liveness:
| Command | Effect |
|---|---|
| LED_SHOW_START_ON / OFF | Show Start LED (D8) solid on or off |
| LED_SHOW_STOP_ON / OFF | Show Stop LED (D9) solid on or off |
| LED_RESET_FLASH / OFF | Show Reset LED (D10) flashing at 2 Hz or off |
| LED_MAINT_ON / OFF | Maintenance LED (D11) solid on or off |
| LED_SERVER_ON / OFF / FLASH | Server LED (D12) solid on, off, or slow blink at 0.5 Hz |
| HEARTBEAT | Sent every 5 seconds. Resets the Bridge’s heartbeat staleness timer. |
| PONG | Response to PING. Must arrive within 1 second. |
Heartbeat fail-safe
If the Bridge does not receive a HEARTBEAT from HelmOS for 15 seconds or longer, it forces the Server Running LED (D12) into a slow blink (0.5 Hz) regardless of the last LED_SERVER_* command received. This is an intentional fail-safe — it tells the operator that HelmOS may be unresponsive even if the USB cable is still connected.
Show-state machine
The Bridge buttons drive the following state transitions on HelmOS:
- STOPPED → RUNNING:SHOW_START (blocked if maintenance is active). Also fires the boot sequence if one exists.
- RUNNING → STOPPED:SHOW_STOP. Cancels all running sequences regardless of origin.
- Any → RESETTING → STOPPED:SHOW_RESET. Cancels all sequences, 5-second reset window, then returns to STOPPED.
MAINT_ON blocks SHOW_START and all trigger-type operations. SHOW_STOP and SHOW_RESET always work as panic-stop affordances.
SERVER_RESET behavior
SERVER_RESET (triggered by holding the blue button for 3 seconds) performs a graceful in-process restart without calling process.exit(). The sequence:
- All running sequences are aborted.
- All WebSocket clients are closed with code 1012 (Service Restart).
- nodes.json is reloaded from disk.
- The serial port is re-opened.
- Show state returns to STOPPED.
The Node.js process keeps the same PID. NSSM does not need to restart the service.