Player Provisioning and Recovery System Requirements
Overview
BrightSign players in large, distributed networks should meet certain provisioning and recovery requirements. Partners who want to set up their own provisioning and recovery systems, rather than using BSN.cloud, should make sure that those systems meet the following requirements.
Each player must be able to provision itself, and once provisioned, periodically check in with the server for updates if configured to do so. The player and server must also be able to initiate a recovery process should the player enter an error state that cannot be fixed by rebooting (for example, filesystem corruption caused by power loss or failure of the storage device).
To meet these requirements, two separate but complementary systems must be developed:
A set of autorun.brs files that can play content, facilitate fault recovery, or provision the player for an HTML/JavaScript playback environment
A request handler server to process recovery/provisioning HTTP requests sent by the player. The request handler delivers an autorun file or other HTTP response depending on player information contained within the header of the request. The request handler database can also contain conditional flags for each player, that enable new autorun scripts to be pushed to specific players in the field. If a partner-specific request handler is not specified in the registry, BSN.cloud provides a default request handler.
Player Provisioning
BrightSign player provisioning integrates the player into your environment, primarily by changing registry settings to reflect that environment and usually by downloading an application or Setup package to the player. The following settings are configured within the registry during BrightAuthor:connected or BSN.cloud provisioning:
BSN.cloud account, username, password, and group
Recovery/provisioning URL, error notification URL, crash report URL
Timezone
Player Registry Entries
The following player registry entries are associated with the provisioning and recovery process. These keys can be modified by accessing the registry’s “networking” section using the roRegistrySection BrightScript object.
Registry Key | Description |
| The URL prefix that is applied to the URLs of the ru, eu, and cu key values. This prefix is not applied to a key value containing a colon. |
| The provisioning/recovery URL used by the player to download an autorun script |
| The URL to which error notifications are posted |
| The URL to which crash reports are posted |
| The password to the recovery handler ( |
The following registry keys are specific to BSN.cloud but can be modified by partners to affect the BSN.cloud registration. You should not store your own information in these sections because it can affect BSN.cloud operations:
Registry Key | Description |
| The name of the BSN.cloud account to which the player belongs. |
| The name of the BSN.cloud user in the account to which the player belongs |
| The BSN.cloud group within the account to which the player belongs |
The account, username, and group registry keys are used for provisioning/recovery with BSN.cloud. A request handler may use these keys, but they are not required.
Player Startup Processes
These processes occur when a BrightSign player boots:
The player connects to a network and obtains an IP address.
The player checks the storage device for an autorun. If an autorun is found, the player will execute the autorun and if none is found, it will proceed with the steps below. See Player Storage for more information about storage devices and device priority (if you have multiple storage devices).
If an IPv4 address exists, the player will attempt to provision over the network.
The player will check for a recovery URL (ru):
If a DHCP Option 43 recovery URL (ru) is found, it will override any registry value for
ru
until the end of the DHCP lease. This URL can be set through DHCP Option 43. See Option 43 to configure a DHCP server to communicate this URL to a BrightSign player.If DHCP Option 43 ru is not found, the ru that is set in the registry will be used.
If there is no registry value for the ru, this step will be skipped.
If the recovery URL is blank, the player will attempt:
Well-known host provisioning: Also known as custom name mapping in your network's DNS server. If an IP address is mapped to brightsign-b-deploy, then the player will attempt to use the associated IP to provision itself automatically.
B-Deploy cloud provisioning: See B-Deploy/Provisioning APIs.
multicast DNS (mDNS): The player will automatically check the standard mDNS location (http://brightsign-b-deploy.local/) and if there is a server on your network with that address, the player will automatically provision itself. However, no other provisioning methods can be active if you want to provision with mDNS. See the Appendix for more information about this option.
The player will retry the provisioning process every 30 seconds until there is a successful response or interruption.
URL Request Parameters
These parameters are used for communicating between a player and the request handler.
Player Request Parameters
The following parameters are included in the header of HTTP GET requests that a player sends to provisioning/recovery URL:
Parameter | Example Value | Description |
|
| The model designation of the BrightSign player |
|
| The family designation of the BrightSign player |
|
| The unique serial number of the player |
|
| The OS (firmware) version currently installed on the player |
|
| The amount of time (in seconds) since the player booted up |
|
| The mode of the current URL request:
|
|
| A flag indicating that the current boot was initiated by a forced reboot due to a crash (this header is only present if true). |
|
| The current autorun and file-system status of each storage device. |
Optional BSN.cloud Keys
Parameter | Example Value | Description |
|
| The |
|
| The |
|
| The |
|
| The p registry value described above |
Storage Status Parameters
The StorageStatus
value contains a list of key-value pairs indicating the status of each storage device. The following storage device keys are returned:
BrightScript Key | Storage Status Key |
USB1: | usb1 |
SD: | sd |
SD2: | sd2 |
SSD: | ssd |
These status values can be returned for each storage device:
Storage Status Value | Description |
| The storage device was not detected. |
| The storage device is present, but an autorun script was not detected. |
| The storage device is present and contains an autorun.brs or autorun.zip file. |
| The storage device is present and contains an autorun.brs or autorun.zip file that failed to load. |
| The storage device is present and contains an autorun.brs or autorun.zip file that encountered a runtime error. |
| The storage device is present but failed a file-system check. This value also implies that attempts to repair the file system also failed. |
Server Response Parameters
The header of a request handler response may contain a single parameter. This parameter can accompany an HTTP 204 or 200 response (even if the response body is empty).
Parameter | Example Value | Description |
Retry-After | 7200 | The amount of time (in seconds) that the player should wait to make a periodic request to the provisioning/recovery URL. If this parameter is not provided, the default request interval will be two hours. |
Player Recovery
If no valid autorun is found, a recovery is triggered. In a recovery, the player pulls down content from the recovery URL (stored in the registry) and attempts to execute it.
The recovery process and the recovery URL should not be confused. While the recovery process uses the recovery URL, some deployment scenarios also use the recovery URL and it is also the provisioning URL in the registry.
Override Recovery
Once the boot process has been completed, the player scans each storage device to determine if one or more devices contain an autorun file:
If at least one device contains an autorun file, the player will delay executing the autorun while a background process sends an HTTP GET request (containing parameters describing the player in the header) to the provisioning/recovery URL:
If the request handler responds using an HTTP code 200 with a non-empty body, the player will use the response body as the new autorun script.
If the request handler responds with an HTTP code 204, or an HTTP code 200 containing an empty message body, the player will execute the preexisting autorun script as normal. The response may also include a "Retry-After" header indicating (in seconds) how frequently the player should check in with the request handler. If this parameter is not specified, the check-in interval will default to two hours.
If no response is received within 20 seconds, the preexisting autorun will be executed. The player will send another request to the request handler after five minutes, then after 10 minutes. It will then make a request once every two hours. If multiple storage devices contain an autorun file, the player will select the first autorun in the following order: USB, SD, SD2, SSD. If it takes too long to check the integrity of a storage device, then that device might be skipped in the order of autorun selection so do not build a system that relies on this order.
If none of the devices contain an autorun, the player will enter last-resort recovery mode.
Periodic Recovery
The player will periodically send an HTTP GET request to the provisioning and recovery URL to determine if the device should be updated.
If no response is received, the preexisting autorun will continue without interruption.
If the request handler responds with an HTTP code 204, or an HTTP code 200 containing an empty message body, the preexisting autorun will continue without interruption. The response may also include a "Retry-After" header indicating (in seconds) how frequently the player should check in with the request handler. If this parameter is not specified, the check-in interval will default to two hours.
If the request handler responds using an HTTP code 200 with a non-empty body, the player will use the response body as the new autorun script.
Last-Resort Recovery
If none of the attached storage devices contain an autorun file, or if the designated autorun encounters an autorun-load-error
or autorun-runtime-error
, then last-resort recovery will begin.
The player sends an HTTP GET request to the provisioning/recovery URL. The header of this request contains information about the player, as well as the status of the storage devices and autorun files on the player: This allows the request handler to determine the correct course of action based on the attributes and current status of the player.
If the request handler responds using an HTTP code 200 with a non-empty body, the player will use the response body as the new autorun script. The autorun script should reboot the player once it performs necessary recovery tasks (the player will not automatically reboot).
If the request handler responds with an HTTP code 204, or an HTTP code 200 containing an empty message body, the player will immediately reboot.
If the request handler does not respond, the player will continue to send requests for 30 minutes before rebooting. Alternatively, a reboot will occur after only 5 minutes if the autorun script has encountered an
autorun-runtime-error
. This process will cycle indefinitely until an autorun script is received from the request handler.
Appendix
mDNS
Multicast DNS is a unique DNS protocol developed for small networks. These diagrams show the differences between a normal DNS setup and a mDNS setup. Note that multicast DNS is not on by default in all networks.
Setting up a Recovery/Provisioning Server
The following workflow diagram describes a simple request handler implementation. This workflow assumes implementation of:
A database that can associate forced-recovery flags with an individual device or group of devices
A provisioning script
A recovery script that first reformats the storage device
A recovery script that does not reformat the storage device
This workflow does not implement the following features:
Different provisioning scripts depending on the DeviceId or Group (or other HTTP GET parameters)
Multiple provisioning or recovery autorun scripts for different storage