Overview

The Remote DWS allows you to view and modify settings on a BrightSign player over the Internet. The Remote DWS API is a REST framework that allows a client application to integrate with Remote DWS functionality.

The client application makes REST calls to the BrightSign WebSockets server, which in turn sends WebSockets messages to BrightSign players. Depending on the operation, the BrightSign player may return information to the BrightSign Websockets server, which will be relayed in the server REST response to the client application.

REST URLs

The following URLs are case sensitive, and the server may return code 426 if the case is not matched exactly.

Production Remote DWS Server: https://ws.bsn.cloud/rest/v1/

Production Authentication URL: https://api.bsn.cloud/2022/06/REST/Token/

Authentication

All Remote DWS calls require a valid authentication token. The target player must belong to the same network for which the token has been granted.

Authentication is carried out using the same OAUTH endpoint as other BSN.cloud services. See https://brightsign.atlassian.net/wiki/spaces/DOC/pages/1313046529/Main+REST+HTTP+API+version+2022+06#MainRESTHTTPAPIversion2022%2F06-AuthenticationWorkflow.

Request Message Format

HTTP requests to Remote DWS resources must be JSON formatted and contain the following URL parameters:

• destinationType  string: The device type. The only currently accepted value is "player".

• destinationName  string: The device serial number

Requests that require a JSON body need to have an outer data object. For instance, if a route expects [bool] enabled then the full JSON body would look like:

Some requests also require resource-specific properties in the URL or request body, as detailed in the URL Parameters and Request Body sections below.

Response Message Format

The server will respond to a REST request with a success or error message, which may also contain resource-specific properties, as detailed in the Response Body sections below.

Returned JSON objects will have an outer object containing the methods below, where data is an error or a result object containing the returned values:

• route string: The route the request was sent to

• method string: The request method

• data object: The returned data

For example:

Endpoints

GET  /info/ 

Retrieves general information about the player.

Response Body

• serial string: The serial number of the player

• model string: The model number of the device (e.g. "XD234")

• connectionType string: The currently active network interface, which can be either "Ethernet" or "WiFi"

• ethernet interfaceConfig{ }: An InterfaceConfig object containing information about the Ethernet connection. This property will only be available if there's a valid Ethernet connection on the player. The Interface Config object can contain the following properties:

  • IPv4 ipConfig{ }: An IPConfig object containing information about the IPv4 configuration. The IPConfig object can contain the following properties:

    • address string

    • netmask string

    • family string

    • mac string

    • internal bool

    • cidr string

  • IPv6 ipConfig{ }: An IPConfig object containing information about the IPv6 configuration

• bootVersion string: The current version of the boot loader

• fwVersion  string: The current version of firmware installed on the player

• upTime string: The amount of time (as a human-readable string) that the player has been powered on and working correctly

• upTimeSeconds int: The amount of time (in seconds) that the player has been powered on and working correctly

• extensions extension[ ]: An array of Extension objects describing Firmware Extensions currently installed on the player

• blessings blessing[ ]: An array of Blessing objects describing proprietary codecs that are currently authorized on the player

GET  /time/ 

Retrieves the date and time as configured on the player. The date/time value is formatted as "yyyy-mm-dd hh:mm:ss <timezone>". This call is identical to using the Node.js® time API.

Request Example

Response Example

PUT  /time/ 

Sets the date/time on the player.

Request Body

• time string: The time to set on the player, formatted as "hh:mm:ss <timezone>"

• date string:  The date to set on the player, formatted as "yyyy-mm-dd"

• applyTimezone bool:  A flag specifying whether the date and time should be applied using the time zone configured on the player (true) or the UTC time zone (false)

Request Example

Response Example

A successful response would be a 200 status code with the following body:

GET /video-mode/ 

Retrieves the currently active video mode on the player.

Response Body

• width int: The screen width

• height int: The screen height

• frames int: The framerate

• scan string: The scan method of the video signal, which can be either progressive ("p") or interlaced ("i")

• name string: The full name of the video mode (a full list of modes can be found here)

• isAutoMode bool: A flag indicating whether the video mode was set using auto mode

• mode mode{ }: A Mode object that gives additional information about the video output. This object can contain the following properties:

  • colorDepth string: The color depth of the video signal ("8bit", "10bit", or "12bit")

  • preferred bool: A flag indicating whether the video mode is the preferred mode

  • overscan bool: A flag indicating whether the video output is using an overscan setting or not

  • modeName string: The full name of the video mode (a full list of modes can be found here)

  • interlaced bool: A flag indicating whether the video output is interlaced (true) or progressive (false)

  • width int: The width of the video output

  • height int: The height of the video output

  • graphicsPlaneWidth int: The width of the graphics plane 

  • graphicsPlaneHeight int: The height of the graphics plane

  • frequency int: The frame rate of the video output

  • dropFrame bool: A flag indicating whether the video timecode utilizes drop frames

  • colorSpace string: The color space of the video signal ("rgb", "yuv420", or "yuv422")

  • colorDepth string: The color depth of the video signal ("8bit", "10bit", or "12bit")

GET /video/{:connector}/output/{:device}/ 

Retrieves information about the specified video output.

Request Example

Response Body

The following fields will be present in the response:

• activeMode: Information about the active video mode on the player

• attached bool: This value indicates if the HDMI^® output is attached or not

• bestMode string: The best video mode for the player. The HDMI connector must be attached because it gets details from EDID result.

• configuredMode: The configured video mode on the player. This can be different than activeMode.

• edid string: Returns the EDID read string of the display connected to the player. If power save is on, zeroes will be returned

• edid_identity: Parses the above string in a JSON format for readability. Requires an HDMI output connected to the player and a display.

• modes: List of all available video modes on the player.

• powerSaveStatus bool: This value indicates the power save status of the display connected to the player.

• resolutions resolutions[ ]: An array of information about the graphics, output, video resolution. Returns result values for height and width.

• status:

  • audioBitsPerSample int

  • audioChannelCount int

  • audioFormat string

  • audioSampleRate int

  • eotf string

  • outputPowered bool

  • outputPresent bool

  • unstable bool

GET /video/{:connector}/output/{:device}/edid/ 

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

See the root endpoint (https://brightsign.atlassian.net/wiki/spaces/DOC/pages/378831527/Remote+DWS+APIs#GET-%2Fvideo%2F%7B%3Aconnector%7D%2Foutput%2F%7B%3Adevice%7D%2F ) for definitions of {:connector} and {:device}.

GET /video/{:connector}/output/{:device}/power-save/ 

Retrieves the power status of the monitor connected to the player (as reported over EDID). See the root endpoint (https://brightsign.atlassian.net/wiki/spaces/DOC/pages/378831527/Remote+DWS+APIs#GET-%2Fvideo%2F%7B%3Aconnector%7D%2Foutput%2F%7B%3Adevice%7D%2F ) for definitions of {:connector} and {:device}.

Response Body

• is_connected bool: A flag indicating whether the monitor is connected to the HDMI output on the player

• is_powered bool: A flag indicating whether the monitor is on (i.e. RX powered) 

• enabled bool: A flag indicating whether power-save mode has been enabled on the HDMI/VGA output

PUT /video/{:connector}/output/{:device}/power-save/ 

Enables or disables power-save mode on the monitor connected to the player (via HDMI, VGA, or Component).

See the root endpoint ( ) for definitions of {:connector} and {:device}.

Request Body

• enabled bool:  Whether or not power save is enabled. 

Request Example

Response Body

• The server will return a success or error message

GET  /video/{:connector}/output/{:device}/modes/ 

Retrieves all available video modes on the specified video output.

See the root endpoint ( ) for definitions of {:connector} and {:device}.

GET /video/{:connector}/output/{:device}/mode/ 

Retrieves the current video mode on the specified video output.

See the root endpoint ( ) for definitions of {:connector} and {:device}.

You can get different mode values by passing the following parameters:

• Best mode: Pass query parameter “?best”

• Active mode: Pass query parameter “?active”

• Configured mode: Pass query parameter “?configured”

Response Body

• mode string: The currently configured video mode on the video output

PUT /video/{:connector}/output/{:device}/mode/ 

Changes the video mode on the player.

See the root endpoint ( ) for definitions of {:connector} and {:device}.

Request Body

A video mode object containing the following value(s):

• modeName string required: The mode (for example, “1920x1080x60p”)

• colorDepth string optional: The color depth of the video signal

• colorSpace string optional: The color space of the video signal

• dropFrame bool: Whether or not the video timecode uses drop frame

• frequency int optional: The frame rate of the video output

• width int optional: The width of the video output

• height int optional: The height of the video output

• graphicsPlaneWidth int optional: The width of the graphics plane

• graphicsPlaneHeight int optional: The height of the graphics plane

• interlaced bool optional:  Whether or not the video output is interlaced

• overscan bool optional: Whether or not the video output is using an overscan setting or not

• preferred bool optional: Whether or not video is the preferred mode

Request Example

Response Body

• The server will return a success or error message

GET /logs/ 

Fetches the player log files as a raw string. The log output is similar to the information generated through serial, Telnet, or SSH on the player.

Response Body

• result string: The raw contents of the player log. Each line is separated by a newline character ("\n")

GET  /download-log-package/ 

Retrieves log files from the player as a download package. The log output is similar to the information generated through serial, Telnet, or SSH on the player.

Response Body

The log files are provided as a .zip file

GET  /crash-dump/ 

Retrieves the crash dump from the player.

Response Body

• result Result: A Result object containing crash-dump files:

  • isRecent bool: A flag indicating if this is the most recent set of crash-dump files

  • crashDumpFiles CrashDumpFiles[ ]: An array of CrashDumpFiles instances. Each CrashDumpFiles instance contains the following entries:

    • fileName string: The name of the file

    • mimeType string: The MIME type of the crash-dump file

    • fileContents string: The crash-dump file contents

PUT  /control/reboot/ 

Reboots the player. The player will not send a response to a reboot request.

Request Body

• crash_report bool: Pass the body parameter {“crash_report": true}. To be used only when directed by BrightSign customer service. This will reboot the player and save a crash-report file to the brightsign-dumps folder. Customer service may request the crash report when helping you troubleshoot a player.

• factory_reset bool: Pass the body parameter {“factory_reset”: true}. This resets the player to factory defaults, erasing all persistent registry settings for networking, security, and other applications.

• autorun string: Pass the body parameter {“autorun”: “disable”}. This disables the current autorun script, and this is especially helpful for debugging purposes.

Request Example

GET /control/dws-password/ 

Retrieves information about the current password of the local DWS (but not the password itself) such as whether the password is blank or invalid.

Response Body

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

• password Password{ }: A Password object that describes the DWS password. The following are possible values:

  • isResultValid bool: A flag indicating whether the DWS password is valid

  • isBlank bool: A flag indicating whether the DWS password is blank (i.e. no password is required)

PUT  /control/dws-password/ 

Sets a new password for the local DWS (or removes the password requirement).

Request Body

• password string: The new local DWS password for the player. The absence of this parameter (or a blank string) will remove the password requirement for the DWS.

• previous_password string: The previous DWS password. This parameter must be included. This value can be an empty string to indicate that the previous password was blank.

Request Example

Response Body

• success bool: A flag indicating whether the password was successfully set

• reboot bool: A flag indicating whether the player will reboot to set the password

GET /control/local-dws/ 

Retrieves the current state of the local DWS.

Response Body

• success bool: A flag indicating whether the local DWS is enabled or disabled

PUT /control/local-dws/ 

Enables or disables the local DWS.

Request Body

• enable bool: A flag indicating whether the local DWS should be enabled or disabled

Request Example

Response Body

• success bool: A flag indicating whether the local DWS was successfully enabled or disabled

• reboot bool: A flag indicating whether the player will reboot to enable/disable the local DWS

GET /files/{:path}/ 

Lists directories / files in the requested :path. You can get raw contents of a directory by passing a query parameter “?raw" with the above API.

Response Body

• type string: Either a directory or file

• path string: The path, for example, "sd"

• stat object: Directory stats from the "fs" module

• files object[ ]: 

  • name string:  Name of the file or directory

  • type string:  Either "file" or "dir"

  • path string: The relative path of the file or directory

  • stat object: File stats from the “fs” module

  • mime string: mime type (available only for type "file")

• storageInfo object: If the path in the URL is a storage device, this returns information about the storage device. For more information, see storageinfo. 

• fileSystemType string: The type of filesystem (for example, "fat32")

• stats object:

  • blockSize int: The size of a native block

  • bytesFree int: The amount of free space

  • filesFree int: The number of used inodes

  • filesUsed int: The number of free inodes

  • isReadOnly bool: A flag indicating whether the filesystem is read only

  • sizeBytes int: The amount of total space

• mountedOn string: The location where the file system is mounted (for example, "/storage/sd")

• contents object[ ]:

  • name string: The name of the file or directory

  • type string:  Either "file" or "dir"

  • path string:  The absolute path of the file or directory

  • stat object: The statistics from the "fs" module 

  • mime string: mime type (available only for type "file")

  • children object[ ]:  This is available only for directory types and will have the same format as "contents"

PUT /files/

Uploads a new file to the player storage.

Request Body

• fileUploadPath string: The path, for example: "/sd"

• files object[]:

  • fileName string: The name of the file

  • fileContents string: The content of the file. It can be provided as plain text or as Data URL.

  • fileType string: Mime type

Request Example

In the examples below, use the FileReader's readAsText() or readAsDataURL() method to derive the fileContents value.

Plain Text

Any file with mime type "text/*", or any “brs”, “json”, “js”, “xml”, “rtf” extension, can be sent as plain text using FileReader's readAsText() method:

Data URL

For all other file types, including zip and media files, use the data URL format using FileReader's readAsDataURL() method:

Response Body

• success bool: A flag that indicates if the operation succeeded or not

• results string[]: The names of the files that were successfully created

POST  /files/{:path}/ 

Renames a file from :path. Path should include the file name. Pass body parameter {"data": {"name": "new-file-name"}}.

DELETE  /files/{:path}/ 

Deletes a file from the player storage.

Response Body

The player will return a success or error message.

DELETE  /storage/{:device_name}/ 

Reformats the specified storage device (see this page for a list of available devices).

Request Body

• fs string: The file system to use when reformatting a storage device. The default value of fs is "exfat".

Request Example

GET /re-provision/ 

Calling this endpoint will re-provision the player (in other words, the B-Deploy setup currently associated with the player will be downloaded, and the device will go through setup again).

The re-provision process involves the following steps:

1. If the “networking” section of the player’s registry contains the access and refresh tokens, it is assumed that the player was previously set up for BSN.cloud. So BrightSign keeps some setup-related keys in the networking section (these keys are listed at right) and deletes the rest of the registry entries. If the networking section does not include access and refresh tokens, it will empty the whole networking section, format the SD card, and reboot to try to provision the player.

2. BrightSign also sets the “deviceSetupComplete“ parameter in the “autorun” section to null, so that the player can set up again. This key is set to 1 only if the player was previously set up through the on-device setup option.

3. The code removes all files from the default storage device (this is almost always the SD card). You do not need to format the storage separately.

4. The player reboots, fetches the setup package from B-Deploy, and re-provisions itself.

Response Body

• success bool: True means that the operation succeeded, False means that the operation failed. If the operation is successful, the player will reboot.