Add Recovery Mode docs - #2
Conversation
gherlein
commented
Mar 4, 2026
gherlein
commented
- interim commit
- interim commit
|
|
||
| **Option A -- BrightAuthor:connected Setup** | ||
|
|
||
| During player setup, the provisioning/recovery URL is one of the fields configured in the setup wizard before writing to the SD card. |
There was a problem hiding this comment.
Note that this is embedded inside bacon based on setup type and not customizable by customers.
|
|
||
| The `ru` value in the registry can be overridden using DHCP Option 43, meaning that with properly configured network infrastructure, players can set themselves up and begin playing content without manual on-site configuration. This is the preferred method for large deployments since it applies to all players on the network segment without touching each device. | ||
|
|
||
| The recovery URL in the DHCP Option 43 payload is prepended with `U` + the ASCII character representing the URL's length. For example, if the URL is 64 characters long, the value would be prepended with `U@` (where `@` is decimal 64 in ASCII). |
There was a problem hiding this comment.
I'm not aware of this prefix requirement. Is this documented somewhere? Maybe handled in OS?
|
|
||
| When a BrightSign player boots and obtains an IP address, it checks for a recovery URL (`ru`) using this priority order: | ||
|
|
||
| 1. **DHCP Option 43** -- if a recovery URL is found via DHCP Option 43, it overrides any registry value for `ru` until the end of the DHCP lease |
There was a problem hiding this comment.
Note: The recovery registry keys(ru, recurl etc. See https://ikb.brightsign.biz/os/brightsign-network-recovery#recovery-url-from-registry-keys) are checked by OS before loading default autorun. Same as the recovery url set via DHCP.
If for some reason the DHCP config was not delivered in the initial boot, DA also checks the recovery url set in OS's network settings, but not the registry key.
The RecoveryMode is also a header that OS handles in the logic of network recovery with registry keys. For the requests DA made, it only adds recoverymode as "default-autorun" in option43 to differentiate that the request is made by DA.
| When a BrightSign player boots and obtains an IP address, it checks for a recovery URL (`ru`) using this priority order: | ||
|
|
||
| 1. **DHCP Option 43** -- if a recovery URL is found via DHCP Option 43, it overrides any registry value for `ru` until the end of the DHCP lease | ||
| 2. **Registry value** -- if no DHCP Option 43 RU is found, the `ru` value stored in the registry is used |
There was a problem hiding this comment.
With what the above mentioned, it means that the registry recovery values and recovery URL in network config are checked first. Then it hands over to default autorun to start with the following:
- DHCP option 43 (set in network settings)
- well known host (to http://brightsign-b-deploy/)
- Bdeploy cloud (to https://provision.bsn.cloud/rest/v2)
- mDNS (to http://brightsign-b-deploy.local/)
|
|
||
| ## Recovery Modes | ||
|
|
||
| There are three recovery modes, all of which hit the same `ru` endpoint. The modes are distinguished by the `recoverymode` header value the player sends in its HTTP GET request, which tells your request handler server exactly what situation it's dealing with. |
There was a problem hiding this comment.
The recoverymode header is something that OS handles. DA only add recoverymode as default-autorun in option 43 mode.
|
|
||
| ### Minimal HTTP Handler | ||
|
|
||
| Your recovery server needs to handle HTTP GET requests and inspect the `recoverymode` header to determine the appropriate response: |
There was a problem hiding this comment.
If default autorun is running, the recoverymode header is only send in DHCP option 43 mode.
| | `serial` | Player serial number | | ||
| | `model` | Player model (e.g., `XT2145`) | | ||
| | `version` | BrightSign OS version | | ||
| | `storagestatus` | Comma-separated status of each storage device (USB, SD, SD2, SSD) | |
There was a problem hiding this comment.
The checking orders are "USB1:/","SD:/","SD2:/","SSD:/". However, recently OS requested to add FLASH:/ for certain models. So the latest implementation is OS decides the list of storage devices.
|
|
||
| | Header | Purpose | | ||
| |--------|---------| | ||
| | `Retry-After` | Number of seconds until next periodic check-in (default: 7200) | |
There was a problem hiding this comment.
Default autorun doesn't use the Retry-After header. Probably used in the OS recovery call.
2 participants
