Overview

You can use the APIs locally with the DWS (to use the Control Cloud APIs for interacting with a player, see Remote+DWS). There are two ways to access these APIs:

1. You can choose to use no authentication.

2. You can choose to use digest authentication. Digest authentication uses a username and a password. The username is always “admin”. The password can be set in three ways:

   1. Use the default, which is the player serial number

   2. Set it through the setup package

   3. Set it using a custom script

Once the password is set, you need to authenticate to access the local DWS APIs. To do this:

• Use BrightSignOS 8.1.21 or higher, such as 8.2, and 8.3 (except 8.3.39.x). Note that BOS 8.3.39.3 and 8.4.6 and higher may have some unexpected behaviors.

• Turn on the local DWS in BrightAuthor:connected in the Control tab of the remote DWS. See DWS Access in Remote Diagnostic Web Server for more information.

• Call the desired API using digest authentication with the local DWS username and password. Note that digest authentication is fairly insecure when used over an insecure transport (HTTP).

The URL prefix is always http://player_ip/api

Advanced Usage

If you choose to set the registry "bbhf" directly instead of through the BrightAuthor:connected UI (described in step 2, above), note that: 

• bbhf is in the networking section of the registry 

• If bbhf is set, the BSN.cloud DWS is enabled, and all DWS APIs are enabled. 

• If bbhf is unset, only the "legacy" DWS and the "legacy" DWS APIs are enabled. The legacy DWS is pre-BSN.cloud and does not use BSN.cloud functions.

API Definitions

The listed APIs are prefixed with the version /v1. To preserve backwards compatibility, BrightSign will create a /v2 version for any API changes and attempt to retain the semantics and behavior of /v1 but this may not be possible. We can not guarantee that this document will be current in every case.

General

GET /v1/ 

Returns a list of all available APIs. 

GET /v1/health/ 

Returns information about the health of a player

GET /v1/download-firmware?url=https://test-url/update.bsfw/ 

The OS file is downloaded from the remote URL to the player and then player is rebooted, updating the OS in the process.

Info Tab

GET /v1/info/ 

Returns basic player information

GET /v1/time/ 

Returns the current time set on the player

PUT /v1/time/ 

Sets the time on the player. 

Request Body

• date string: The recommended format is: "YYYY-MM-DD"

• time string: The recommended format is: "HH:mm"

• applyTimezone bool: This value decides if the date and time passed is in UTC or not (the default is false).

GET /v1/video-mode/ 

Returns the current video mode of the player

Logs Tab

GET /v1/logs/ 

Returns the serial logs

GET /v1/download-log-package/ 

Directly downloads the player’s serial log

Control Tab

PUT /v1/control/reboot/ 

Reboot the player

Request Body

• crash_report bool: Setting this parameter to true reboots the player and saves a crash-report file to the brightsign-dumps folder. Only use this when directed by BrightSign customer service, which may request the crash report when helping you troubleshoot a player.

• factory_reset bool: Setting this parameter to true resets the player to factory defaults, erasing all persistent registry settings for networking, security, and other applications.

• autorun string: Set to “disable” to disable the current autorun script, which is helpful for debugging purposes.

PUT /v1/control/dws-password/ 

Resets or changes the DWS password. 

Request Body

• password string: This is the password value that you want to set. Passing a blank string "" will remove the existing password.

• previous_password string: This optional parameter is the old password value

GET /v1/control/dws-password/ 

Returns whether the local DWS password is blank or invalid.

GET /v1/control/local-dws/ 

Returns whether the local DWS is enabled or not

PUT /v1/control/local-dws/ 

Enables or disables the local DWS on the player. 

Request Body

• enable bool: Whether the local DWS is enabled or not (it is enabled by default)

Storage Devices Tabs

GET /v1/files/:directoryPath/ 

Lists directories and files in the requested path.

DELETE /v1/files/:filePath/ 

Removes a file.

POST /v1/files/:filePath/ 

Renames a file. 

Request Body

• name string: The new file name

PUT /v1/files/:path/ 

Uploads one or more files. The request body needs to be of type form-data. If you add one or more parameters of type file (the name of the parameter does not matter), it will upload the selected file(s). 

If you do not add a file parameter and the request has a slash at the end, it will create a directory. For example this request body, without a file parameter, will create a directory called test: /v1/files/sd/test/

Diagnostics Tab

DELETE /v1/storage/:device/ 

Formats a storage device

GET /v1/diagnostics/ 

Runs network diagnostics on the player and returns the result in JSON format.

GET /v1/diagnostics/dns-lookup/:address/ 

Runs a DNS lookup for an address, which can be a hostname or IP address.

GET /v1/diagnostics/ping/:ipAddress/ 

Pings the address passed in the request. This does not work for hostnames, only for IP addresses.

GET /v1/diagnostics/trace-route/:address/ 

Runs trace-route on the player. You can optionally pass the boolean query parameter ?resolveAddress to resolve IP addresses in the result.

GET /v1/diagnostics/network-neighborhood/ 

Returns the network neighborhood on the player.

GET /v1/diagnostics/network-configuration/:interfaceName/ 

Gets the network configuration on the player

PUT /v1/diagnostics/network-configuration/:interfaceName/ 

Applies a test network configuration on the player. You should use GET to get the configuration parameters before setting it using this API.

GET /v1/diagnostics/interfaces/ 

Returns list of applied network interfaces on the player.

GET /v1/diagnostics/packet-capture/ 

Returns the current status of packet capture operation. 

POST /v1/diagnostics/packet-capture/ 

Starts a packet capture operation

Request Body

• filename string: The name of the packet capture file. If you don't pass this string, 'capture.pcap' is the default.

• net_interface string: The name of the network interface for which we are performing packet capture. 'eth0' is the default.

• duration int: The duration for which the packet capture runs in seconds. The default is 300 seconds (5 minutes).

• maxpackets int: The maximum number of packets to capture before concluding the process. 0 is the default value.

• snaplen int: The maximum size of each packet. Specifying 0 will instruct the function to capture the entire packet no matter the size.

• filter string:  A field for conditional filtering of packets. This operation uses standard pcap syntax. This string is empty by default.

DELETE /v1/diagnostics/packet-capture/ 

Stops a packet capture operation

GET /v1/diagnostics/telnet/

Returns information about whether or not Telnet is enabled on the player, and the port number on which it is enabled if it is. This is only available in BOS 9.0.110 or 8.5.46 and above.

Request Example

GET /api/v1/diagnostics/telnet/ HTTP/1.1
Host: {{player_ip_address}}
Authorization: Bearer {{UserAccessToken}}
Accept: application/json

Response Example

A successful response is a 200 and this response body:

{
    "enabled": true,
    "portNumber": 23
}

PUT /v1/diagnostics/telnet/

This is only available in BOS 9.0.110 or 8.5.46 and above.

Request Body

• enabled boolean: Enable or disable Telnet on the player

• portNumber integer: The port number on which to enable Telnet

• reboot boolean: This optional parameter reboots the player immediately after executing this operation. It is true by default.

Request Example

The example request parameters and headers are set as follows:

PUT /api/v1/diagnostics/telnet/ HTTP/1.1
Host: {{player_ip_address}}
Authorization: Bearer {{UserAccessToken}}
Accept: application/json
Content-Type: application/json
Content-Length: 75

This is the example request body:

{
   "enabled": true
   "portNumber": "23"
}

Response Example

{
    "success": true, 
    "reboot": true // Indicates whether the player will reboot 
}

GET /v1/diagnostics/ssh/

Returns information about whether or not SSH is enabled on the player, and the port number on which it is enabled if it is. This is only available in BOS 9.0.110 or 8.5.46 and above.

Request Example

The example request parameters and headers are set as follows:

GET /api/v1/diagnostics/ssh/ HTTP/1.1
Host: {{player_ip_address}}
Authorization: Bearer {{UserAccessToken}}
Accept: application/json

Response Example

A successful response is a 200 and this response body:

{
    "enabled": true,
    "portNumber": 22,
    "password": true // Indicates that a value is set
}

PUT /v1/diagnostics/ssh/

This is only available in BOS 9.0.110 or 8.5.46 and above.

Request Body

• enabled boolean: Enable or disable SSH on the player

• portNumber integer: The port number on which to enable SSH

• password string: Sets the plain-text login password for the SSH connection

• reboot boolean: This optional parameter reboots the player immediately after executing this operation. It is true by default.

• obfuscatedPassword string: This optional parameter sets the login password for the SSH connection. The password should previously have been obfuscated using a shared secret. Contact support@brightsign.biz to learn more about generating a key for obfuscation and storing it on the player.

Request Example

The example request parameters and headers are set as follows:

PUT /api/v1/diagnostics/ssh/ HTTP/1.1
Host: {{player_ip_address}}
Authorization: Bearer {{UserAccessToken}}
Accept: application/json
Content-Type: application/json
Content-Length: 65

This is the example request body:

{
    "enabled": true,
    "portNumber": 22,
    "password": {{password}}
}

Response Example

{
    "success": true, 
    "reboot": true // Indicates whether the player will reboot 
}

Remote Snapshot Tab

POST /v1/snapshot/ 

Captures a snapshot of the currently played content on the player

Video Tab

Note that :connector supports only HDMI^® and that :device is the numeric index of the output, which is currently only 0.

GET /v1/video/:connector/output/:device/ 

Retrieves information about the specified video output.

An example of :connector is “hdmi” (without the quotes), and an example of :device is “0”, for example: http://192.168.4.43/api/v1/video/hdmi/output/0/

GET /v1/video/:connector/output/:device/edid/ 

Returns the EDID information from a compatible monitor/television connected to the video output.

An example of :connector is “hdmi” (without the quotes), and an example of :device is “0”, for example: http://192.168.4.43/api/v1/video/hdmi/output/0/edid/

GET /v1/video/:connector/output/:device/power-save/ 

Retrieves the power status of the monitor connected to the player. 

An example of :connector is “hdmi” (without the quotes), and an example of :device is “0”, for example: http://192.168.4.43/api/v1/video/hdmi/output/0/power-save/

PUT /v1/video/:connector/output/:device/power-save/ 

Enables or disables power-save mode on the monitor connected to the player.

Request Body

• enabled bool: Whether the power-save mode on the monitor is enabled or disabled 

GET /v1/video/:connector/output/:device/modes/ 

Returns a list of all available video modes on the specified video output.

An example of :connector is “hdmi” (without the quotes), and an example of :device is “0”, for example: http://192.168.4.43/api/v1/video/hdmi/output/0/modes/

GET /v1/video/:connector/output/:device/mode/ 

Retrieves the current video mode on the specified video output. 

An example of :connector is “hdmi” (without the quotes), and an example of :device is “0”, for example: http://192.168.4.43/api/v1/video/hdmi/output/0/mode/

Example

GET /api/v1/video/hdmi/output/0/mode

PUT /v1/video/:connector/output/:device/mode/ 

Changes the video mode on the player. You should first send a GET request to find the body parameters of this API, but only the parameter below is required (all others are optional):

Request Body

• modeName string: See Supported Video Modes for a list of the possible valid strings for your device

Example

PUT /api/v1/video/hdmi/output/0/mode/{"modeName": "1920x1080x50p"}

Advanced Tab

GET /v1/system/supervisor/logging/ 

Returns the current logging level on the player. The default value is INFO.

PUT /v1/system/supervisor/logging/ 

Sets the logging level on the player.

Request Body

• level int: The integer values correspond to the logging levels: TRACE (3), INFO (2), WARN (1), ERROR (0)

Registry Tab

GET /v1/registry/ 

Returns the entire registry dump. The hidden registry sections are not returned in this response.

Request Example

The example request parameters and headers are set as follows:

GET /api/v1/registry/ HTTP/1.1
Host: {{player_ip_address}}
Authorization: Bearer {{UserAccessToken}}
Accept: application/json

Response Body

• success bool: If the operation is successful

• value object: The keys are the names of the registry sections. These are some examples:

  • brightscript string: The BrightScript key-value pairs

  • networking string: The networking key-value pairs

GET /v1/registry/:section/:key/ 

Returns a particular key value for a specified section and key.

Segment Values

• section string: The name of the registry section

• key string: The name of the registry key

Request Example

The example request parameters and headers are set as follows:

• section is set to html

• key is set to use-brightsign-media-player

GET /api/v1/registry/html/use-brightsign-media-player/ HTTP/1.1
Host: {{player_ip_address}}
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json

PUT /v1/registry/:section/:key/ 

Creates registry values. Do a GET first to see which keys are available.

Segment Values

• section string: The name of the registry section (for example, "html" or "networking")

• key string: The name of the registry key

Request Example

The example request parameters and headers are set as follows:

• section is set to html

• key is set to use-brightsign-media-player

PUT /api/v1/registry/html/use-brightsign-media-player/ HTTP/1.1
Host: {{local_ip_address}}
Authorization: Bearer {{UserAccessToken}}
Accept: application/json
Content-Type: application/json
Content-Length: 33

This is the example request body:

{
   "value": "0"
}

DELETE /v1/registry/:section/:key/ 

Remove the specified registry values.

Segment Values

• section string: The name of the registry section (for example, "html" or "networking")

• key string: The name of the registry key

Request Example

The example request parameters and headers are set as follows:

• section is set to html

• key is set to use-brightsign-media-player

DELETE /api/v1/registry/html/use-brightsign-media-player/ HTTP/1.1
Host: {{player_ip_address}}
Authorization: Bearer {{UserAccessToken}}
Accept: application/json

DELETE /v1/registry/:section/ 

Deletes an entire registry section

Request Example

The example request parameters and headers are set as follows:

• section is set to test_section

DELETE /api/v1/registry/test_section/ HTTP/1.1
Host: {{player_ip_address}}
Authorization: Bearer {{UserAccessToken}}
Accept: application/json

GET  /v1/registry/recovery_url/ 

Retrieves the recovery URL stored in the player registry

Request Example

• recovery_url is the recovery URL in the player registry

GET /api/v1/registry/recovery_url/ HTTP/1.1
Host: {{player_ip_address}}
Authorization: Bearer {{UserAccessToken}}
Accept: application/json

Response Body

• success bool: A flag indicating whether the request was successfully read

• value string: The recovery URL

PUT /v1/registry/recovery_url/ 

Updates the recovery URL in the player’s registry. 

Request Body

• url string: The value of the recovery URL 

Request Example

The example request parameters and headers are set as follows:

• url is set to www.google.com

PUT /api/v1/registry/recovery_url/ HTTP/1.1
Host: {{player_ip_address}}
Authorization: Bearer {{UserAccessToken}}
Accept: application/json
Content-Type: application/json
Content-Length: 37

Request Body

{
   "url": "www.google.com"
}

Downloading a File From Player Storage

To directly download a file from player storage, add ?contents&stream to the end of the URL. Here is a sample workflow (assuming a base URL of http://192.168.0.12/api/v1):

1. Create a snapshot on the SD card under the remote_snapshots using POST /v1/snapshot

2. The response will be the name of the snapshot (for example, img-2021-12-29-10-49-27.jpg).

3. To directly download the snapshot created on the player: GET http://192.168.0.12/api/v1/files/sd/remote_snapshots/img-2021-12-29-10-49-27.jpg?contents&stream

4. If you enter only ?contents, you get the file in the base64 encoding.

Using HTTPS with the Local DWS

Generating a Self-Signed Certificate and Key

To do this, choose one of the following two methods:

1. Run this code: 

   openssl req -nodes -new -x509 -keyout dws.key -out dws.crt

2. OR run the following code and use the 'dws.key' and 'dws.crt' files. The other files can be deleted later.

   openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer
   
   openssl genrsa -out dws.key 4096
   
   openssl req -new -key dws.key -out client.req
   
   openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out dws.crt

Making the Certificate and Key Files Accessible

The operating system will look for files with known names at the root of the default storage. To make the certificate and key files you generated findable, either:

• Name the files dws.crt and dws.key, OR

• Put the names of the files in the networking registry using the keys ldws_cert_file_name, ldws_key_file_name

Then put the files at the root of the default storage.