BrightSign Supervisor Troubleshooting

This guide describes how to diagnose and recover BrightSign devices running the signageOS supervisor extension. If you have not installed the supervisor yet, follow the BrightSign Supervisor Provisioning guide first.

How the supervisor starts

On every boot, the firmware mounts the supervisor extension and starts it only when the registry value signageos/enabled is 1. The supervisor then downloads the management snippet from signageos/sos_url on first activation and keeps it on disk for subsequent boots. Most problems come down to one of these steps failing — the sections below cover each of them.

Reading supervisor logs

DWS Logs tab

The supervisor mirrors its log output into the device log visible in the Logs tab of the Diagnostic Web Server (DWS). Look for lines tagged:

• sos-bootstrap: — the supervisor entry process (device readiness, registry configuration, snippet download)
• sos-snippet: — the signageOS management process itself

The device log is kept in memory only, so it always shows the current boot. If you need logs from a failed boot, capture them before rebooting the device.

Device does not appear in Box

Go through this checklist in order:

1. Extension installed — the DWS Info page must list the signageOS extension. If it is missing, the .bsfw package was not installed; re-run the installation steps. Remember that a major firmware upgrade removes the extension — you must install the .bsfw package again afterwards.
2. Supervisor enabled — the DWS Registry tab must show enabled: 1 in the signageos section. If not:

   registry write signageos enabled 1

3. Snippet URL set — the signageos section must contain a valid sos_url. The URL must use HTTPS — plain http:// URLs are rejected for security reasons and the supervisor will not start.
4. Network and DNS — the supervisor waits for DNS to resolve the snippet host before downloading. Check the DWS Network page and make sure the device can reach the internet (or your proxy) and resolve public hostnames.
5. Device registered — the device serial number (the Unique ID from the DWS Info page) must be registered via Bulk Provisioning in Box, or the registry must contain organization_uid for automatic verification.
6. Crash-loop fail-safe not tripped — check the crash_count value in the registry; see the next section.

After fixing any of these, reboot the device from the DWS Control tab.

Crash-loop fail-safe (reset counter)

The supervisor has a built-in fail-safe against boot loops: if it crashes 3 times in a row before running stable for at least 60 seconds, it refuses to start on subsequent boots. This prevents a broken supervisor from taking the device into an endless reboot loop with no window to recover it.

The counter is stored in the registry as signageos/crash_count:

• It is incremented every time the supervisor starts.
• It is reset to 0 automatically once the supervisor has been running for 60 seconds, and on every graceful shutdown or scheduled reboot.
• Only a real crash — the process dying within the first 60 seconds — leaves the counter incremented.

Symptoms

• The device is no longer connected in Box, and no sos-bootstrap: lines appear in the DWS Logs tab after a reboot.
• The DWS Registry tab shows crash_count: 3 (or higher) in the signageos section.
• /var/log/signageos.log (SSH) contains a line like:

  FAIL-SAFE TRIPPED: crash_count=3 >= 3, not starting supervisor

Recovery

1. Reset the counter via the DWS Registry tab:

   registry write signageos crash_count 0

2. If the supervisor was crashing because of a broken snippet, also force a re-download (see the next section) before rebooting.
3. Reboot the device from the DWS Control tab.

Rapid power-cycling

Unplugging the device repeatedly within the first 60 seconds of boot bypasses the graceful shutdown and increments the counter each time — so three quick power cuts in a row can trip the fail-safe even though the supervisor never crashed. If a device stops connecting after power interruptions, reset crash_count as described above.

Force re-download of the snippet

The management snippet is downloaded once and reused on every boot. If the stored snippet is broken — for example, the device crashes right after start, or it is stuck on a version that no longer works — you can force a fresh download without reinstalling the extension:

registry write signageos force_download 1

Then reboot the device. On the next boot, the supervisor deletes the stored snippet, downloads a fresh copy from sos_url, and clears the flag automatically — you do not need to set it back to 0.

Combine with the reset counter

A broken snippet is the most common cause of a tripped crash-loop fail-safe. When recovering such a device, set both values before rebooting:

registry write signageos force_download 1
registry write signageos crash_count 0

You can also point the device at a different snippet version by changing sos_url and setting force_download 1 in the same step.

Do not downgrade below 2.5.0

Supervisor is supported from version 2.5.0 and higher — never point sos_url at an older version or downgrade the application below 2.5.0 in Box. Older versions do not contain the supervisor runtime, so the device would crash on boot and can trip the crash-loop fail-safe described above.

Debug logging

To get verbose logging from the supervisor, set the debug_storage registry value and reboot:

registry write signageos debug_storage debug=*

The extra output appears in the DWS Logs tab and in /var/log/signageos.log. To limit the output to a specific namespace, use a pattern instead of *, e.g. debug=@signageos/display-brightsign:*. Delete the key to turn verbose logging off again:

registry delete signageos debug_storage

Remote debugging with Node.js DevTools

The supervisor runs as pure Node.js processes and supports the standard Node.js inspector. Enable it via the registry and reboot:

registry write signageos inspect_port 9229

After the reboot, two inspector endpoints are available on the device:

Process	Port
Bootstrap (entry process)	9229
Snippet (management process)	9230 (always inspect_port + 1)

Open chrome://inspect in Chrome on a computer in the same network, click Configure..., and add both <deviceIp>:9229 and <deviceIp>:9230. Both processes then appear as remote targets. Delete the inspect_port key and reboot to close the inspector again.

Registry reference

All supervisor configuration lives in the signageos registry section, manageable from the DWS Registry tab:

Key	Required	Example	Description
enabled	yes	1	Enables the supervisor. Any other value keeps it stopped.
sos_url	yes	https://cc.signageos.io/brightsign/snippet.js	HTTPS URL the management snippet is downloaded from on first boot. The default URL always serves the latest released supervisor snippet.
organization_uid	no	<uuid>	Organization UID for automatic device verification. Without it, the device must be registered via Bulk Provisioning.
force_download	no	1	Re-download the snippet on next boot. Clears itself automatically.
crash_count	no	0	Crash-loop fail-safe counter, managed automatically. Write 0 to recover a device that refuses to start the supervisor.
debug_storage	no	debug=*	Enables verbose debug logging.
inspect_port	no	9229	Opens the Node.js inspector (bootstrap on this port, snippet on port + 1).

Disabling or removing the supervisor

• Temporarily disable — set registry write signageos enabled 0 and reboot. The extension stays installed but does not start; set the value back to 1 and reboot to re-enable it.
• Fully remove — the extension is part of the firmware storage; removing it requires a factory reset.