Option 43

1 Overview
- 1.1 Recovery/Bootstraping
- 1.2 Provisioning Setup Overview
2 DHCP Server Configuration
- 2.1 Request/Response String Formats
- 2.2 Player Configuration
- 2.3 Verifying Option 43 Configuration
- 2.4 Encoder Example
3 Provisioning Server Configuration
- 3.1 Provisioning Script
- 3.2 Provisioning Package

A BrightSign player can download its autorun script and other presentation assets from a URL value stored in its registry. This feature can be used to provision a player in the field. It also allows a player to automatically recover from run-time or load errors associated with the autorun script.

The URL 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 page outlines how to set up a provisioning system that uses DHCP Option 43.

The B-Deploy Appliance may also use DHCP Option 43. The solution outlined on this page makes use of a third-party provisioning server (i.e. one you set up yourself) rather than the B-Deploy Appliance.

Overview

Recovery/Bootstraping

When a BrightSign player boots (and at periodic intervals while running), it will direct an HTTP GET request at the provisioning/recovery URL stored in the player registry, which is blank as a factory default. The header of the HTTP GET request includes the following parameters:

Parameter	Example Value	Description
`Account`	`bsaccount`	The `a` registry value
`User`	`bsuser`	The `u` registry value
`Group`	`bsgroup`	The `g` registry value
`Password`	`bspassword`	The `p` registry value
`DeviceModel`	`XD1230`	The model designation of the BrightSign player
`DeviceFamily`	`cheetah`	The family designation of the BrightSign player
`DeviceId`	`X2F2CU0000065`	The serial number of the player
`DeviceFwVersion`	`4.7.146`	The version of firmware currently installed on the player
`DeviceUpTime`*	`240`	The amount of time (in seconds) since the player booted up
`RecoveryMode`*	`override`	The mode of the current URL request: `override`: The initial HTTP GET request of a player with a valid autorun script `periodic`: Subsequent HTTP GET requests of a player with a valid autorun script `last-resort`: The HTTP GET request of a player without a valid autorun script
`CrashDump`*	`yes`	A flag indicating that the current boot was initiated by a forced reboot due to a crash (this header is only present if true)
`StorageStatus`	`usb1=none;sd=autorun;` `sd2=storage;ssd=none;`	The current autorun and file-system status of each storage device.

If the HTTP GET request is successful, the player will attempt to utilize whatever content was downloaded as an autorun script. Note that the player does not make any checks to determine if the content is actually a .brs autorun file before attempting to run it.

Provisioning Setup Overview

The following infrastructure is required to provision players using DHCP Option 43:

DHCP server: Located on the local network and configured for Option 43 communication
Provisioning script URL: A URL that returns the .brs provisioning script
Provisioning package URL: A URL that returns the .zip provisioning package
Firmware update URL:(optional) A URL that returns a firmware update file if needed

DHCP Server Configuration

Request/Response String Formats

When a BrightSign player requests information from a DHCP server, the query will include an Option 60 string containing the vendor identity of the player: [BS_OEM_ID] + “ “ + [BS_OEM_MODEL] (e.g. “BrightSign XD1230”). The DHCP server can use this string to match the correct Option 43 response for the vendor and model number of the device. Alternatively, the correct response can be determined using other information available to a DHCP server, including subscriber ID where port-based IP allocation is used.

The response should be an Option 43 string consisting of TLV (type-length-value) encoded data, and the provisioning/recovery URL should be defined using Tag 85 (0x55 or ASCII “U”). The tag and length are 1 byte each. The length should also be encoded using hex or ASCII.

While the formatted response value can be straightforwardly set on a Linux server, configuring Microsoft servers requires additional steps.

Player Configuration

When the player receives the Option 43 response, it will override the default URL in the registry with the value in the response string. The value supplied by the DHCP server is not saved in persistent storage; the registry override remains in effect only as long as the DHCP lease remains active. If necessary, the recovery/provisioning script can permanently change the registry value using BrightScript functions.

The player can store a different URL for each network interface. When multiple DHCP responses are received from different network interfaces, the player will choose to recover or bootstrap using the first non-empty URL value in the following interface order:

Ethernet
WiFi
3G

Verifying Option 43 Configuration

To verify that the player is responding correctly to the DHCP server, access the BrightSign shell via the serial port (see the BrightScript Debug Console page for more details). At the BrightSign prompt, type "ifconfig": If the Option 43 action has been successful, the new provisioning/recovery URL will be returned; if the action was unsuccessful, the default BrightSign Network URL will be returned.

To verify that the player actually sends provision/recovery requests to the URL, you can look at the logs from the web server delivering the recovery script. You can also use tcpdump or Wireshark on the local network to view the HTTP GET request from the player.

Encoder Example

The following simple webpage script can be used to convert a URL into the proper hexadecimal format for use with Option 43 strings:

<html>
<head>
<title>BrightSign Option 43 Recovery URL encoding</title>
<script>
function convertUrl()
{
    url = document.getElementById("url").value;
    out = document.getElementById("out");
 
    // First construct the required TLV as a byte array
    data = [];
    data.push(0x55);         // Tag
    data.push(url.length);
// Length
// Value
    for(var i = 0; i < url.length; i++)
    {
        data.push(url.charCodeAt(i));
// ASCII only, please.
    }
 
    // Now convert to a hex string.
    // (Other formats could also be produced)
    hex = ""
    for(var i = 0; i < data.length; i++)
    {
        b = (data[i] + 256).toString(16).substr(-2).toUpperCase();
        hex = hex.concat(b)
    }
 
    out.value = "option 43 hex " + hex;
 
    return false;  // Prevent submit/reload
}
</script>
</head>
<body>
<h1>BrightSign Option 43 Recovery URL encoding</h1>
<p>Enter the required Recovery URL below:
<form onsubmit="return convertUrl()">
<input type="text" size="100" id="url">
<input type="submit" value="Convert">
</form>
<textarea id="out" rows=4 cols=120 readOnly="true"></textarea>
</body>
</html>

Provisioning Server Configuration

Provisioning Script

Once the player receives the Option 43 response, it will make an HTTP GET request to the URL contained in the response. The provisioning server should examine the StorageStatus header in the request. If "autorun" is present in the string, it should return code 204; otherwise, it should return code 200 with the .brs provisioning script in the response body.

The provisioning script should, in turn, overwrite the recovery URL in the registry and download the provisioning package from a separate URL.

By default, IIS servers do not allow .brs files because they are not a registered MIME type. If you're using an IIS server to distribute the .brs provisioning script, make sure to register .brs as a "text/plain" MIME type.

The provisingScript.brs file included with this document provides a template provisioning script for downloading a presentation package and/or firmware file. To use this script, you will need to replace the following values in the script with values that are specific to your application:

##fileName1##: The name of the file after it is downloaded to local storage (e.g. "autorun.zip")
##fileType1##: The file type, which can be either "presentation" or "firmware"
##url1##: The download URL for the file
##addBsHeaders1##: A flag indicating whether to add headers to the HTTP request, including device values such as the serial number and firmware version. This value can be true or false.
##optionalHeaders##: A set of one or more optional headers to add to the HTTP request. These headers are only added if ##addBsHeaders1## is replaced with true. The following example shows how to format an optional header in the script:

"xfer.AddHeader(\"Authorization\", \"Bearer " + authToken + "\")"

There are a second set of values in the script (##fileName2##, ##fileType2##, etc.). If you want to download both a presentation package and firmware file, replace these with appropriate values. If you want the script to download a single file only, set the string values to invalid and the Boolean value to false.

The script also contains a ##recoveryUrl## field, which is the new recovery URL that will be written to the player registry. This value is likely the same as the URL specified in the Option 43 response, which will otherwise revert to default when the DHCP lease expires.

Provisioning Package

The provisioning script should call additional URLs to download the presentation package and/or firmware update files. The presentation package should be a .zip file containing necessary files.

If provisioning is carried out with the included provisioningScript.brs script, the player will automatically unpack a downloaded .zip file without requiring any additional script or naming conventions. If you're using your own provisioning script (or as an extra precaution), name the presentation package autorun.zip and include the autozip.brs script, which is also included with this document.