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:

You can choose to use no authentication.
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.

All POST and PUT API calls have response and request bodies of type JSON.

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 or directory

POST /v1/files/:filePath/

Renames a file.

Request Body

name string: The new file name

PUT /v1/files/:path/

Uploads files or creates directories. The request body needs to be of type multipart/form-data (see RFC 7578). 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).

To create a directory, remove the form-data and file parameter from the body, and add the directory as the URL parameter, :path. 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

You must disable the autorun before reformatting the SD card on your device.

To disable the autorun, use the PUT API /v1/control/reboot with body parameter { “autorun”:”disable” }, as described in this page. This can also be done in the local DWS Diagnostics tab.

ON THIS PAGE

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:

Response Example

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:

Response Example

A successful response is a 200 and this response body:

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:

This is the example request body:

Response Example

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

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

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:

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

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

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

Applications rely on the values they have set in the registry. Please be mindful of what you type to avoid putting the player in an unstable state.

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

This is the example request body:

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 /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

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

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

Request Body

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):

Create a snapshot on the SD card under the remote_snapshots using POST /v1/snapshot
The response will be the name of the snapshot (for example, img-2021-12-29-10-49-27.jpg).
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
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:

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

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.