HelmOS

HelmOS

Windows Deployment Guide

This guide walks through deployingHelmOSandCuemasteron a mini PC running Windows 10 or 11 Pro. When you're done, the mini PC will runHelmOSas a Windows Service that starts at boot, serve theCuemasterdashboard on port 3000, drive the operator Bridge over USB serial, and reach every Polaris field node on the TRUENORTH 2.4 GHz Wi-Fi network.

The whole install takes about 30 minutes if the network gear is ready. Walk top-to-bottom; each step has a verification line so you can confirm before moving on.

At a glance

Recommended network layout

Run the Wi-Fi side on a dedicated travel router (GL.iNetGL-MT300N or similar). It runs the TRUENORTH SSID, hands out DHCP from 10.0.0.10 upward, and sits on a wired ethernet drop into the mini PC. The mini PC's wired NIC gets the static address 10.0.0.1. Windows Mobile Hotspot works in a pinch but is harder to lock down to channel, IP range, and password; for production, use the external router.

Step 1 — System requirements

• Windows 10 Pro or 11 Pro (Home will not run the service reliably).
• Wired ethernet port available on the mini PC.
• Local admin account for installation steps.
• Internet access during install only (for Node.js download); the production system runs offline.

Step 2 — Install Node.js 20 LTS

• Download the Windows installer (.msi) from nodejs.org and install Node 20 LTS for all users. Accept the default install location.
• During the installer,uncheckthe “Tools for Native Modules” option. Theserialportmodule ships prebuilt binaries; you don't need Python or Visual Studio Build Tools.
• Open a new PowerShell window after installation completes and verify:

Step 3 — Copy HelmOS to the mini PC

Pick one of these depending on what's easiest:

Option A: copy from a USB stick

• On the dev machine, copy the entirehelmdirectory (the whole project tree) to a USB stick.
• On the mini PC, copy it toC:\helm— the final layout should look like:

Option B: copy over the network from another Windows PC

Open PowerShell on your dev machine:

Option C: clone from a git remote

If the project is in a repo (recommended for ongoing updates), clone directly on the mini PC:

Step 4 — Install dependencies and build Cuemaster

Open PowerShell as your normal user (not as Administrator) and run:

Step 5 — Place the initial show file

Step 6 — Configure the static IP 10.0.0.1 on the wired NIC

• Identify the wired ethernet adapter. From an elevated PowerShell:

• Set the static IP (substitute theInterfaceIndexfrom above for <ifIndex>):

• Verify withipconfig— the wired adapter should now show10.0.0.1/255.255.255.0with no default gateway (the show network is air-gapped from the internet).

4Step 7 — Set up the TRUENORTH Wi-Fi

Preferred path: external travel router

Plug the router's WAN port into a free port on the mini PC's wired NIC or a switch on the same subnet. Configure the router as an access point with these settings:

This keeps the Wi-Fi software off the mini PC and lets you swap routers without touchingHelmOS.

Fallback path: Windows Mobile Hotspot

If you can't add a router, Windows can broadcast TRUENORTH from its onboard Wi-Fi:

• Settings → Network & Internet → Mobile hotspot → On.
• Edit the name to TRUENORTH and set a strong password.
• Set the band to 2.4 GHz (under the same panel).
• Note: Mobile Hotspot uses Windows's own DHCP pool (192.168.137.x). You'll need to renumber the Polaris nodes accordingly, or set static IPs on each. The external-router path avoids this.

Step 8 — Install HelmOS as a Windows Service with NSSM

• Download NSSM from— extract the ZIP and copynssm.exe(the 64-bit one) toC:\helm\bin\nssm.exe.
• Open an elevated PowerShell (Run as Administrator) and install the service:

• A GUI window opens. Fill in:
• Application tab — Arguments:C:\helm\helmos\src\index.js
• Application tab — Startup directory:C:\helm
• Details tab — Display name:HelmOS(Northstar Show Systems)
• Details tab — Startup type:Automatic
• Log on tab —Local System account (or a dedicated 'helmos' local account with read/write toC:\ProgramData\Helm).
• Environment tab — paste:

• I/O tab — Output (stdout):C:\ProgramData\Helm\helmos.log
• I/O tab — Error (stderr):C:\ProgramData\Helm\helmos.err.log
• File rotation tab —enable rotation: rotate when file is 10 MB; keep last 5 files. Logs grow forever without this.
• ClickInstall service, then start it from PowerShell:

• Watch the live log:Get-Content C:\ProgramData\Helm\helmos.log -Wait— look for{"level":"info","msg":"helmos.ready","port":3000}.

Step 9 — Connect the Bridge and confirm the COM port

• Plug the Arduino UNO R4WiFiinto a USB port. Windows assigns it a COM number — find it with:

• IfHelmOSpicked it up automatically (VID 0x2341), the log shows{"msg":"bridge.connected","path":"COM3"}. Done.
• If auto-detect picked the wrong COM port or there are multiple USB-serial gadgets attached, pin it explicitly. Open NSSM again, edit the service:

• On the Environment tab, add:BRIDGE_PORT=COM3(substitute your COM number).
• Restart the service:Restart-ServiceHelmOS.

Step 10 — Open the Windows Defender firewall

By default Windows blocks inbound connections to port 3000. Allow it on private and domain profiles only (TRUENORTH should not be flagged public).

Verification checklist

Pushing updates

When you have a newHelmOS/Cuemasterbuild to deploy, repeat the file copy and rebuild on the mini PC:

Troubleshooting

Service won't start

• Read both logs inC:\ProgramData\Helm\:helmos.logisHelmOS'sown structured output;helmos.err.logis NSSM's wrapper errors (missing node.exe, wrong path, etc.).
• Walk the service config:C:\helm\bin\nssm.exe getHelmOSApplication,Arguments,AppDirectory.

Bridge isn't detected

• Open Device Manager → Ports (COM & LPT). The Arduino should show a COM number.
• If the device shows as “Unknown” without a driver, install the Arduino IDE once — it ships the CDC driver. After that, the device should bind to a COM port even without the IDE running.
• Confirm the COM number, then setBRIDGE_PORTon the service.

Polaris nodes don't show online

• From the mini PC:curl http://10.0.0.10/status— if that fails, the node isn't on TRUENORTH yet.
• Verify the wired link between the mini PC and the router is up:ping 10.0.0.2(the router's own LAN IP).
• If using Mobile Hotspot, verify the Polaris nodes have IPs in the 192.168.137.x range and updatenodes.jsonto match.

Cuemaster loads but shows BRIDGE OFFLINE forever

• The serial port is detected but no traffic. Open Device Manager and check the Arduino is not stuck in bootloader mode (its COM number changes briefly during reset).
• Restart the service:Restart-ServiceHelmOS.HelmOSwill reopen the port and the Bridge announces its maintenance-key state ~2.5 s after the link comes back.

Cuemaster works locally but not from the operator iPad

• Confirm the iPad is on TRUENORTH (not a guest network).
• Confirm the firewall rule allows the network profile the iPad is using:Get-NetFirewallRule-DisplayName 'HelmOS*' | Format-ListProfile,Enabled,Action.
• From the iPad's Safari, browse to http://10.0.0.1:3000 — bookmark it. Touch ID/Face ID can speed re-opens; pin the bookmark to the home screen for a single-tap launch.