Page tree
Skip to end of metadata
Go to start of metadata

ON THIS PAGE

The B-Deploy server allows for automated provisioning of BrightSign players over the Internet. This page outlines how to develop an application and file server (FS) that will integrate with the BrightSign B-Deploy server. 

Required Components

To integrate with the B-Deploy server, you will need to create two components:

  • Application: The application registers player serial numbers and setup files with the B-Deploy server.
  • File Server: The HTTP file server hosts presentation packages for distribution to players. Each presentation package is a ZIP file named autorun.zip, which contains presentation files along with an autozip.brs boilerplate script. In most cases, the boilerplate script will not need to be modified.

Workflow Overview

B-Deploy

  1. The user uploads one or more presentation packages to the file server (FS) and records the download URL for each package.
  2. The user creates a device setup using an API, which sends a JSON payload containing device setup parameters to the B-Deploy server. The device setup contains the download URL for the presentation package.
  3. Using an API, the user registers device serial numbers that should be associated with the device setup. These serial numbers are also communicated to the B-Deploy server.

 

BrightSign Player

  1. The user inserts a blank storage device (e.g. a microSD card) into the player and powers it on.
  2. The player boots up and, lacking an autorun.brs or autorun.zip file on the storage device, launches on-screen Device Setup.

    Important

     The user should avoid interacting with the Device Setup screen, which may prevent automated provisioning.

  3. When on-screen Device Setup times out, the player queries the B-Deploy server (unless the local network infrastructure is configured for provisioning via the B-Deploy Appliance or DHCP Option 43).

  4. The B-Deploy server responds with a provisioning script URL if the player serial number in the request matches a serial number in the database. If the B-Deploy server does not recognize the serial number, it will return status code 204.
  5. The player reboots, downloads the provisioning script, and runs it. The provisioning script directs the player to download the device-setup package from B-Deploy.
  6. The player reboots and runs device setup, which sets the recovery URL to a handler on B-Deploy.
  7. The player reboots, downloads a recovery script from the recovery URL, and runs it. The recovery script instructs the player to download the presentation package from the file server.
  8. The player reboots and runs the presentation.

JSON Specification

Credentials Object

The Credentials object is used to validate the REST client in the /authenticate POST call for the B-Deploy server. It returns an AuthToken string that must be passed into all subsequent API calls. The token is valid for one hour, after which a new token must be obtained.

Note

The credentials are provided by BrightSign. 

{
"username": "example@brightsign.biz", // Required
"password": "****" // Required
}

Device Object

The Device object is used for /device GET and POST calls on the B-Deploy server. POST calls to the /device endpoint can contain a single Device object or an array of Device objects if adding multiple devices simultaneously.

{
  "_id": "61bc4064-4a06-11e6-beb8-9e71128cae66", // Unique identifier for the Device object; not required for multi-device POST, PUT, or GET
  "username": "example@brightsign.biz", // Required; used to query devices for this user
  "serial": "72E38V002984", // Required
  "name": "MyPlayer", // Optional
  "model": "4K1142", // Optional; this field is required if using the "FirmwareVersion" update mechanism in the Device Setup object.
  "desc": "Julian's Desk", // Optional
  "setupId": "80223029", // Optional; the ID of a Device Setup object to associate with the device; a null value instructs the device to perform a default DHCP setup.
  "url": "http://bobs.cms.com", // Required; the URL for the presentation package
  "userdata": "", // Optional; up to 1024 bytes; must be base64-encoded; the player will include this field as a header when making the GET request to the "url".
}

Device Setup Object

The Device Setup object is used for /setup GET and POST calls on the PSS server.

Most parameters in the Device Setup object are optional. The following parameters are required:

  • "_id": Not required for multi-setup POST, PUT, and GET calls.
  • "username": Queries the device-setup list for a user.
  • "Wired"/"Wireless": One of these fields needs to be specified. If the "UseDHCP" parameter is set to true, it is the only required parameter. If the "UseDHCP" parameter is set to false, then the following manual IP parameters need to be specified: "IpAddress", "SubnetMask", "DefaultGateway", "DNS1"/"DNS2"/"DNS3".
{
       "_id": "61bc4064-4a06-11e6-beb8-9e71128cae77", // Unique identifier for the Device Setup object. Not required for multi-setup POST, PUT or GET
       "username": "example@brightsign.biz", // Required; used to query device setups for this user
       // Setup Package-specific Properties
       "PackageName": "My Setup Package 1", // [string]
       // Device Settings
       "Name": "My Test Unit 1", // [string]
       "Description": "Test Unit", // [string]
       "ConcatUnitNameAndSerial": false, // [bool]
       "Model": "HD222", // [DeviceModel]
       "TargetTimeZone": "EET", // [string]
       "ScreenColor": "RGB:000000", // [string]
       "SplashScreenUrl": "http://bsnmdev.s3.amazonaws.com/stas/49fd6ffa681c25c9e4ce498fabb5409a", // [URI]
       "ContentCheckPeriod": "1.00:00:00", // [TimeSpan]
       "ContentDownloadsEndTime": null, // [Nullable<TimeSpan>]
       "ContentDownloadsStartTime": null, // [Nullable<TimeSpan>]
       "HealthReportingPeriod": "00:15:00", // [Nullable<TimeSpan>]
       "HealthReportingEndTime": "09:00:00", // [Nullable<TimeSpan>]
       "HealthReportingStartTime": "17:00:00", // [Nullable<TimeSpan>]
       "NetworkSettings": {
             "Hostname": "my.device.1", // [string]
             "ProxyServer": "http://gw.mycompany.biz", // [URI]
             "ProxyBypass": [ // [string[]]
                 "content.local",
                 "token.service"
             ],
             "TimeServer": "ntp://time.brightsignnetwork.com", // [URI]
             "WiredConnectionPriority": true, // [bool]
             "WirelessConnectionPriority": false, // [bool]
             "Wired": { // Nullable
                    "UseDHCP": false, // [bool]
                    "IpAddress": "192.168.0.1", // [Nullable<IPv4Address>]
                    "SubnetMask": "255.255.255.0", // [Nullable<IPv4Address>]
                    "DefaultGateway": "192.168.0.0", // [Nullable<IPv4Address>]
                    "DNS1": "192.168.0.125", // [Nullable<IPv4Address>]
                    "DNS2": "74.38.99.135", // [Nullable<IPv4Address>]
                    "DNS3": null, // [Nullable<IPv4Address>]
                    "RateLimitDuringInitialDownloads": null, // [Nullable<uint>]
                    "RateLimitInsideContentDownloadWindow": null, // [Nullable<uint>]
                    "RateLimitOutsideContentDownloadWindow": null, // [Nullable<uint>]
                    "ContentDownloadEnabled": true, // [bool]
                    "TextFeedsDownloadEnabled": true, // [bool]
                    "MediaFeedsDownloadEnabled": true, // [bool]
                    "HealthReportingEnabled": true, // [bool]
                    "LogsUploadEnabled": true // [bool]
             },
             "Wireless": { // Nullable
                    "SSID": "hall_devices", // [string]
                    "Passphrase": "A8200E99648B54D90E8740B1CD4A199CFF99C38DE85123486A44CA96A999B0A6D", // [string]
                    "UseDHCP": true, // [bool]
                    "IpAddress": null, // [Nullable<IPv4Address>]
                    "SubnetMask": null, // [Nullable<IPv4Address>]
                    "DefaultGateway": null, // [Nullable<IPv4Address>]
                    "DNS1": null, // [Nullable<IPv4Address>]
                    "DNS2": null, // [Nullable<IPv4Address>]
                    "DNS3": null, // [Nullable<IPv4Address>]
                    "RateLimitDuringInitialDownloads": 10240000, // [Nullable<uint>]
                    "RateLimitInsideContentDownloadWindow": 10240000, // [Nullable<uint>]
                    "RateLimitOutsideContentDownloadWindow": 256000, // [Nullable<uint>]
                    "ContentDownloadEnabled": true, // [bool]
                    "TextFeedsDownloadEnabled": true, // [bool]
                    "MediaFeedsDownloadEnabled": false, // [bool]
                    "HealthReportingEnabled": true, // [bool]
                    "LogsUploadEnabled": false // [bool]
             }
       },
       "Beacons": [ // Nullable
       {
         "Mode": "iBeacon" // [DeviceBeaconMode]
         "Name": "BeaconP1", // [string]
         "UUID": "3AE3D364-3EB6-463D-9DD6-987F4D888160", // [GUID]
         "Major": 64, // [ushort]
         "Minor": 32, // [ushort]
         "PowerLevel": 42 // [short]
      },
      {
         "Mode": "eddystone-uid" // [DeviceBeaconMode]
         "Name": "BeaconP2", // [string]
         "NamespaceID": "AQIDBAUGBwgJAA==", // [byte[]] (BASE64)
         "InstanceID": "/wIDBAUG", // [byte[]] (BASE64)
         "PowerLevel": 25 // [short]
      },
      {
         "Mode": "eddystone-url" // [DeviceBeaconMode]
         "Name": "BeaconP3", // [string]
         "URL": "http://development.brightsignnetwork.com/signin.aspx", // [URI]
         "PowerLevel": -10 // [short]
      }
       ],
       "RemoteSnapshotSettings": { // Nullable
             "Enabled": true, // [bool]
             "CaptureInterval": "00:15:00", // [Nullable<TimeSpan>]
             "CountLimit": 100, // [Nullable<ushort>]
             "ImageQuality": 80, // [Nullable<byte>]
             "ScreenOrientation": "Landscape" // [Nullable<ScreenOrientation>]
       },
       "LogsSettings": { // Nullable
             "EnableDiagnosticLog": true, // [bool]
             "EnableEventLog": false, // [bool]
             "EnablePlaybackLog": true, // [bool]
             "EnableStateLog": false, // [bool]
             "EnableVariableLog": false, // [bool]
             "UploadAtBoot": true, // [bool]
             "UploadTime": null // [Nullable<TimeSpan>]
       },          
       "LocalWebServerSettings": { // Nullable
             "Enabled": true, // [bool]
             "EnableUpdateNotifications": true, // [Nullable<bool>]
             "UserName": "admin", // [string]
             "Password": "AAE193CA3F6D2DFACBACCFBF59FFAE03EB1717C592EE27DDC251C143AE9BB750D" // [string]
       },
       "DiagnosticWebServerSettings": { // Nullable
             "Enabled": true, // [bool]
             "Password": "A537DB234C17C74033945AB019400825C7614B955F80288DCFBCCE2A4E147F0F6" // [string]
       },
       "EnableNetworkDiagnostics": false, // [bool]
       "EnableEthernetTest": true, // [bool]
       "EnableWirelessTest": false, // [bool]
       "EnableInternetTest": false, // [bool]
 
 
"FirmwareVersion": "", // [string] Optional; specifies the firmware update version to download and apply during the device-setup process; for the update mechanism to work, the "model" field must be specified in the associated Device object; this value can be one of the following: "Production", "Beta", "MinimumCompatible".
"FirmwareURL": "" // [string] Optional; specifies the URL that the player will use to download the firmware-update file; if this parameter is specified, it takes precedence over the "FirmwareVersion" parameter.
}

API Specification

The following are attributes of the B-Deploy API:

  • GET requests for multiple items support pageNum and pageSize query-string parameters. A status code of 400 is returned in case of an error in the parameters.
    • If pageNum (starting at 1) is supplied, the corresponding page is returned (starting at 1). If pageNum is omitted, the first page is returned.
    • The maximum pageSize is 100. If pageSize is omitted, the maximum is returned. The response object also contains "total" and "match" properties, which correspond to the total number of records and the number of records returned on a given page, respectively.
    • GET responses are JSON objects. The content-type is "application/json".
    • Request bodies are JSON objects. The content-type must be "application/json".
    • A token is required for all API calls except to the /authenticate endpoint. Contact BrightSign Support to obtain credentials. The token must be provided as a header in the HTTP request: Authorization: Bearer <token>

 

Resource URI

Method

Query String Parameters

Request

Response

/rest/v1/authenticate

POST

 

Body: Credentials

Body: auth token

Headers: Expiries (in RFC 1123 date format)

/rest-device/v1/device

GET

[pageNum] [pageSize] [serial] [username]

[account] [setupId] [model]

Headers: Authorization

Device | Device[]

POST

 

Body: Device | Device[]

Headers: Authorization

_id | _id[]

PUT

 

Body: Device

Headers: Authorization

 

DELETE

_id

Headers: Authorization

 

/rest-device/v1/device/:_id

GET

 

Headers: Authorization

Device

/rest-setup/v1/setup

GET

[id] [pageNum] [pageSize] [username] [account]

Headers: Authorization

DeviceSetup | DeviceSetup[]

POST

 

Body: DeviceSetup |

DeviceSetup[] 

Headers: Authorization

_id | _id[]

PUT

 

Body: DeviceSetup

Headers: Authorization

 

DELETE

_id

Headers: Authorization

 

/rest-setup/v1/setup/:_id

GET

[pageNum] [pageSize] [username] [account]

Headers: Authorization

DeviceSetup

  • No labels