B-Deploy (DOCS-1098)

ON THIS PAGE

The B-Deploy service 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 B-Deploy.

Authentication

All B-Deploy calls require a valid authentication token. Authentication is carried out using the same OAUTH endpoint as other BSN.cloud services. See Step 8 on this page for more details.

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

The user uploads one or more presentation packages to the file server (FS) and records the download URL for each package.
The user creates a device setup by posting a JSON payload containing device setup parameters to the B-Deploy server. The device setup contains the download URL for the presentation package.
Via the B-Deploy API, the user registers device serial numbers that should be associated with the device setup.

BrightSign Player

The user inserts a blank storage device (e.g. a microSD card) into the player and powers it on.
The player boots up and, lacking an autorun.brs or autorun.zip file on the storage device, launches on-screen Device Setup.
The user must avoid activating the player using the Device Activation screen (or setting up the player with the Device Setup screen). These actions may prevent automated provisioning.
When on-screen Device Setup times out, the player queries the B-Deploy server (unless the local network infrastructure is configured for provisioning via DHCP Option 43).
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.
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.
The player reboots and runs device setup, which sets the recovery URL to a handler on B-Deploy.
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.
The player reboots and runs the presentation.

VLAN Network Setup via B-Deploy

Using B-Deploy with VLAN(s) has a few components to consider while configuring the network controller and the B-Deploy Setup Package. In order to download and apply a setup package from B-Deploy on your player, an internet connection must first be connected without any manual setup needed. This internet connection could be established through various methods; either through a physical ethernet connection (or BrightSign USB-C Ethernet adapter) possibly using DHCP to avoid a manual configuration needed; or WiFi configured through the player's On-Device Setup WiFi Access Point Mode (see url.com); or connecting a BrightSign Mobile cellular modem. Keep in mind that the setup package may configure this current network interface by adjusting, removing, or leaving it as is once the B-Deploy Setup Package has been applied.

If the setup package download has VLANs configured, your network controller interface must be configured to maintain internet connectivity. For example, if you download a setup package via ethernet that prioritizes Wifi, and Wifi is expected to have an internet connection, the network controller must have Wifi configured with an internet connection. Then, although ethernet was used to download the setup package, Wifi will be the only interface used for network traffic since it is a higher priority. The same is true for BrightSign Mobile and USB ethernet interfaces that are downloaded via ethernet.

If the setup package does change the current configuration of the physical ethernet, the ethernet port in the network controller must support the VLAN configuration in the setup package. If the current settings use ethernet to download the setup package, then the network controller must allow the default/native VLAN (untagged) connectivity to support tagged VLANs.

rest-setup/v2/setup

GET

Retrieves a device setup from the B-Deploy server.

URL Parameters

username: The username associated with the device setups you wish to retrieve
_id: The ID of the device setup to retrieve. If this parameter is not included in the URL, the GET request will return all device setups associated with the username

Response Body

[string] error: Error information related to the return data. This value is null if there are no errors.
[Result{}] result: Contains a single Device Setup object if the _id is specified in the URL; otherwise, this property contains the following:
- [int] total: The total number of Device Setup objects that belong to the B-Deploy account
- [int] matched: The number of Device Setup objects contained in the response
- [deviceSetup[] deviceSetups: An array of Device Setup objects. Each Device Setup object can contain the following properties:
  - [string] _id: A system-supplied ID for the Device Setup object
  - [string] createdAt: A UTC timestamp indicating when the Device Setup object was created. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ
  - [string] updatedAt: A UTC timestamp indicating when the Device Setup object was last modified. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ
  - [bDeploy{}] bDeploy: A BDeploy object containing the following properties:
    - [string] username: The BSN.cloud username
    - [string] networkName: The BSN.cloud network name
    - [string] packageName: The client-defined name for the Device Setup package. This value must be unique among Device Setup packages that belong to your person entity.
  - [tokenEntity{}] bsnDeviceRegistrationTokenEntity: A TokenEntity object containing the following properties:
    - [string] token: The device registration token
    - [string] scope: The scope of the device registration token
    - [string] validFrom: The beginning of the token validity window
    - [string] validTo: The end of the token validity window
  - [string] bsnGroupName: The name of the BSN.cloud group to which provisioned devices will be assigned. This value defaults to the "Default" group if undefined.
  - [string] setupType: The Device Setup type. This value is currently always "bsn".
  - [string] version: The B-Deploy Cloud version. This value should currently be "2.0.0"
  - [string] deviceName: The name given to devices that are provisioned with the Device Setup package
  - [string] deviceDescription: The description give to devices that are provisioned with the Device Setup package
  - [string] url: An optional value of the Partner Application URL specified for a device to use when finding the application to download.

POST

Adds a new device setup to the B-Deploy server.

Request Body

The following list includes only required properties for device-setup creation.

[string] version: The B-Deploy Cloud version. This value should currently be "2.0.0".
[string] setupType: The device-setup type: "bsn", "lfn", "sfn", "standalone", or “partnerApplication”
[string] bsnGroupName: The name of the BSN.cloud group to which provisioned devices will be assigned. This value defaults to the "Default" group if undefined.
[string] url: An optional value of the Partner Application URL specified for a device to use when finding the application to download.
[boolean] remoteDwsEnabled: A flag indicating whether the Remote DWS is enabled or disabled on the player
[bDeploy{}] bDeploy: A BDeploy object containing the following properties:
- [string] username: The BSN.cloud username
- [string] networkName: The BSN.cloud network name
- [string] packageName: The client-defined name for the Device Setup package. This value must be unique among Device Setup packages that belong to your person entity.
- [string] client: An optional name of the client creating the Device Setup package. This value can be arbitrary and is not related to the BSN.cloud client identifier or client secret tokens.
- [string] url: An optional url to a custom application URL. This value will be ignored if setupType is NOT set to “partnerApplication”.
[tokenEntity{}] bsnDeviceRegistrationTokenEntity: A TokenEntity object that is used to register the device with a BSN.cloud network. See Main REST HTTP API version 2020/10 for more information about the authentication workflow or the following example of how to generate a registration token:

curl --location --request POST 'https://api.bsn.cloud/2020/10/REST/provisioning/setups/tokens/' \
--header 'Accept: application/json' \
--header 'Accept-Encoding: gzip,deflate' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer 5BfFL3xblKTifXntsGMEBFVSEEIUGh0iibjR3rTWVt3UKLz0MoPiFvcyz9I8R0DVwxL2MiasqpwCrcpQscN4RQUeO3V1EI8QKQzToBoVFkLAGg3qmqssDSgFIt1OIc2P' \
--data-urlencode 'grant_type=user_access_token' \
--data-urlencode 'user_access_token=5BfFL3nblKTifXxtsGMEBFVSEEIUGh0iibjR3rTWVt3UKLz0MoPiFvcyz9I8R0DVwxL2MiasqpwCrcpQscN4RQUeO3V1EI8QKQzToBoVFkLAGg3qmqssDSgFIt1OIc2P' \
--data-urlencode 'client_id=gA82Yeaa' \
--data-urlencode 'client_secret=MLZZQPy0-6ziP-473F-bKdB-b6c5kSeUOsOD'

The client_id and client_secret are issued to the customer and the bearer token is retrieved from the standard authentication endpoint. If the network that the player is to be registered to is specified in the authentication request:

curl --location --request POST 'https://api.bsn.cloud/2020/10/REST/Token/' \
--header 'Accept-Encoding: gzip,deflate' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer TkyMFdjAcvJYjDyxpqaOZde1j4jgHNf6xYNaVzcV293oLbr43LOrsFQ1Nrz74lA6TRjzFbyNg8L1pczWAqSH2CJAjy1yCU6UBvbJrUJa7xOVlw0Lj4oSXW5wsvJ3sL8C' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=gA82Yeaa' \
--data-urlencode 'client_secret=MLZZQPy0-6ziP-473F-bKdB-b6c5kSeUOsOD' \
--data-urlencode 'username=BrS-deployment-automation/mkubasak@brightsign.biz' \
--data-urlencode 'password=0eE6f1ypY7$a'

[string] token: A device-registration token. The server returns this token, which allows devices to provision themselves for a BSN.cloud network. Note that this is not a user token.[string] scope: The scope of the device registration token[string] validFrom: The start of the validity date for the token. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.[string] validTo: The end of the validity date for the token. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

Response Body

[string] error
[string] result: The ID of the Device Setup object

PUT

Updates an existing device setup on the B-Deploy server. You must include the _id property in the Device Setup object to specify the device setup to update.

Request Body

[string] _id: The ID of the Device Setup object to modify
[string] version: The B-Deploy Cloud version. This value should currently be "2.0.0".
[string] setupType: The Device Setup type. This value is currently always "bsn".
[string] bsnGroupName: The name of the BSN.cloud group to which provisioned devices will be assigned. This value defaults to the "Default" group if undefined.
[string] url: An optional value of the Partner Application URL specified for a device to use when finding the application to download.
[boolean] remoteDwsEnabled: A flag indicating whether the Remote DWS is enabled or disabled on the player
[bDeploy{}] bDeploy: A BDeploy object containing the following properties:
- [string] username: The BSN.cloud username
- [string] networkName: The BSN.cloud network name
- [string] packageName: The client-defined name for the Device Setup package.
- [string] client: An optional name of the client creating the Device Setup package. This value can be arbitrary and is not related to the BSN.cloud client identifier or client secret tokens.
[tokenEntity{}] bsnDeviceRegistrationTokenEntity: A TokenEntity object that is used to register the device with a BSN.cloud network.
- [string] token: A device-registration token. The server returns this token, which allows devices to provision themselves for a BSN.cloud network. Note that this is not a user token.
- [string] scope: The scope of the device registration token
- [string] validFrom: The start of the validity date for the token. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.
- [string] validTo: The end of the validity date for the token. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

DELETE

Deletes a device setup from the B-Deploy server.

URL Parameters

_id: The ID of the device setup to delete.

rest-device/v2/device

GET

Retrieves a Device object associated with the B-Deploy account.

URL Parameters

_id: The ID of the Device object to retrieve. If this parameter is not included in the URL, the GET request will return all Device objects associated with the account

Response Body

[string] error: Error information related to the return data. This value is null if there are no errors.
[Result{}] result: Contains a single Device object if the _id is specified in the URL; otherwise, this property contains the following:
- [int] total: The total number of Device objects that belong to the B-Deploy account
- [int] matched: The number of Device objects contained in the response
- [device[] Players: An array of Device objects. Each Device object can contain the following properties:
  - [string] _id: The ID of the Device object
  - [string] setupId: The _id of the Device Setup object associated with the Device object. The player will use the associated device setup to provision itself.
  - [string] serial: The serial number of the player represented by the Device object
  - [string] createdAt: A UTC timestamp indicating when the Device Setup object was created. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ
  - [string] updatedAt: A UTC timestamp indicating when the Device Setup object was last modified. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ
- [string] url: An optional value of the Partner Application URL specified for a device to use when finding the application to download.
  - [string] client
  - [string] __v

POST

Adds a Device object to the B-Deploy account.

Request Body

[string] serial: The serial number of the player represented by the Device object
[string] setupName: The name of the setup file
[string] NetworkName: The name of the network
[string] url: The URL from which the player will download its presentation as part of the final provisioning step
[string] setupId: The _id of the Device Setup object associated with the Device object. The player will use the associated device setup to provision itself.

Response Body

[string] error
[[string] result: The ID of the Device object

PUT

Modifies a Device object associated with the B-Deploy account.

[string] serial: The serial number of the player represented by the Device object
[string] url: The URL from which the player will download its presentation as part of the final provisioning step
[string] setupId: The _id of the Device Setup object associated with the Device object. The player will use the associated device setup to provision itself.

DELETE

Removes a Device object from the B-Deploy account.

URL Parameters

_id: The ID of the Device object to delete.