Control Cloud API Integration Guide
The BSN.cloud Control Cloud is the new player provisioning, diagnostics, and control system for BrightSign Players. The Control Cloud allows for automated provisioning of your customers' players to your CMS solution. You can also use the Control Cloud to perform a host of diagnostic actions on a BrightSign player, including retrieving/modifying settings, updating firmware, rebooting, performing a factory reset, and even passing down custom data.
This document will walk you through the Control Cloud integration process. In the course of this document, you will learn how to provision BrightSign players out of the box (and to help your customers do the same, if necessary) and interact with the player over the Internet using the Control Cloud REST API.
Glossary of Terms
BSN Control Cloud: A set of player management and deployment services that include the B-Deploy API, Remote DWS, Authentication services, and a limited set of BSN APIs
Partner: The content management system (CMS) to integrate with BrightSign
Client Credentials: A set of credentials, provided by BrightSign, that allows the partner to create and manage networks
Customer: The individual purchasing content-management services from the partner in order to manage BrightSign players
Person: A set of credentials (email and password) that allows an individual to create networks and access them as a user.
Network: The structure for managing and monitoring players on BSN.cloud:
A network can have any number of players, but a player can only belong to a single network at a time. To switch a player to another network, the device entry must be deleted from the original network on the BSN and B-Deploy services.
A network can have multiple users (i.e. persons), and persons can belong to multiple networks. The person who creates the network is the network administrator, but the administrator may give other users equivalent privileges.
A newly created network defaults to Control Cloud. One or more player subscriptions are required to upgrade the network to Content Cloud.
Resources
The following resources are used for BSN.cloud Content Cloud operations. Note that Content Cloud networks have a limited set of BSN endpoints they can call.
Obtaining BSN.cloud Client Credentials
To retrieve authorization tokens for your customers, you will need Client Credentials for the BSN Cloud. Contact support@brightsign.biz to obtain your Client Credentials.
Determine Your Network Structure
Before creating BSN.cloud networks, you will need to determine how to manage customer players on BSN.cloud. There are three options:
One network for all customers: You manage a single network for all customers' players. There is no way to segregate players by user, so you could not give customers direct access to Remote DWS or B-Deploy functionality.
You create networks for customers: You will create a network for each of your customers. You can create an additional user on the network to give the customer access (as creator, you remain the network owner). The customer can either have full permissions or a subset of permissions.
Each customer creates a network: The customer creates a network using the BSN.cloud UI (or a custom UI that you create using the APIs). If you want access to your customers' networks, they will need to add you to the network or hand over their credentials.
Determine Network Interface Priorities
BrightSignOS Metric Logic:
Prior to OS 8.4.6, the BrightSignOS (BOS) updated the metrics (interface priority) of wired and wireless interfaces using 0 as the highest metric value, and 1 as the secondary value, when specified through BrightAuthor:connected.
In BrightSignOS 8.4.6 and above, the BOS will assign metrics in the following cases:
Targeted Interfaces: Once the player has successfully connected to BSN.cloud, metrics will be updated in interfaces provided by a BrightAuthor:connected Device Setup package.
Discovered Interfaces: Once the player has successfully connected to BSN.cloud, metrics will be updated in interfaces which are discovered either through a physical interface connection before power is applied or as a hotplug after power has been applied.
Metric value logic is used to determine the actual value used when applying to the BOS. Relative to the order of all the Targeted Interfaces and Discovered Interfaces, the metric will be calculated by starting the "metric assignment" at 100. The location (or index) of the interface is ordered relative to other interfaces, then multiplied by 10, then increased by 100. For example:
Interface | Index | Final Metric Value ((Index * 10) + 100) |
|---|---|---|
eth0 | 0 | 100 |
wlan0 | 1 | 110 |
ppp0 | 2 | 120 |
usb0 | 3 | 130 |
Metric Range Definitions
These metric range definitions are loose - there are no actual restrictions.
0 - 99: Used for interfaces which are not assigned by the BOS, possibly because the player is not connected to BSN.cloud or older BOS version, or autorun. These would be explicitly assigned by older software.
100 - 199: Used for the BOS when assigning metrics.
200 - n: Used for interfaces which are not assigned by the BOS. This may be because the player is not connected to BSN.cloud, or an older BOS version or autorun are running, where these were not assigned by any software.
Disabling BrightSignOS Metrics
To keep the BOS from applying metrics for all interfaces, set supervisor_apply_metrics to false in the networking section registry key.
Determine Your Provisioning Workflow
Depending on the network structure you've decided on, there are two workflows for provisioning customer players for your CMS and the Control Cloud:
Option A - Partner Provisions Customer Devices: You will use the B-Deploy APIs to generate a Device object for each player (using the serial number) and associate the Device objects with one or more Device Setup objects. You can either add Device objects using your Client Credentials (for example, before shipping them from your warehouse), or you can have customers enter the serial numbers themselves (which would require you to build a customer-facing UI that interacts with the B-Deploy APIs on the backend). When the customer connects players to the Internet on-site, they will contact the B-Deploy servers and provision themselves for your CMS.
Option B - Customer Links Control Cloud Network with Partner CMS: Have the customer add players to their Control Cloud network, which your CMS has access to. Players that are registered on the customer's network will provision themselves for your CMS. This option requires that you gain access to a customer network; there are two ways to do this:
You create a Control Cloud network for the customer (using the Control Cloud APIs) and hand the credentials to the customer.
The customer creates an account using the new BrightSign device activation scheme. The customer will then need to hand the the credentials over to you.
Hosting a Provisioning Package
You can use the B-Deploy application to set up players for your CMS application To do this, you will need to host a fixed application URL that BrightSign players can use to download a provisioning package. Contact BrightSign for help generating a provisioning package.
Work with the Control Cloud APIs
Once you've taken the above steps, go to the Postman Collections for a walkthrough of Control Cloud tasks, including the following:
Creating a person
Creating a network
Performing person/network authentication
Adding a Device Setup object and Device record to the B-Deploy server
Provisioning a player
Retrieving a list of players on a BSN.cloud network
Making Websockets calls to the player
Security
The BrightSign player exposes some APIs that serve up information required by various internal processes. These are open APIs, which are not secure. However they can only be called by other processes running on the player, not externally, and they do not serve any sensitive information.