Option 43

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.

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:

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:

1. Ethernet

2. WiFi

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

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.