(New) Player Provisioning and Recovery

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

• URL prefix for most stored URLs. This is the base URL for the recovery URL (for example, bsn.com), to which endpoints can be appended.

• 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.

The following registry keys are specific to BSN.cloud but may also be useful for partners:

The following player registry entries are used by standard scripts. They may or may not be used as part of the provisioning and recovery process:

Player Startup Processes

These processes occur when a BrightSign player boots:

1. The player connects to a network and obtains an IP address.

2. The player checks the storage device for a custom autorun. If an autorun is found, the player will execute the autorun and if it’s not found, it will proceed with the steps below.

3. If an IPv4 address exists, the player will attempt to provision over the network.

4. If a DHCP Option 43 recovery URL (ru) is found, the player will download an autorun script from the URL value stored in its registry.

   • 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.

5. If no DHCP Option 43 ru exists but an ru is set in the registry, the player will provision with this ru.

6. 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): If your network supports multicast, 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.

7. 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:

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:

These status values can be returned for each storage device:

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). 

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:

1. 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.

2. 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.

1. 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