rDWS Other Endpoints

Base URL for these endpoints: https://ws.bsn.cloud/rest/v1/

_________________________________________________________________________

GET /files/{:path}/

Lists the directories and/or files in a path

Segment

path string: The path to the directories or files

Query String Parameter

raw optional: Returns the raw contents of a directory

Request Example

GET /rest/v1/files/sd/autorun.brs/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json

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/{:path}

Uploads a new file to the player storage

If you are uploading zip and media files, you should use BOS version 8.5.44 or 9.0.101 or later.

Segment

path string: The path is the folder in which you want to upload the file (for example: "/sd").

Request Body Parameters

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

The following request example would be used with one of the two request body examples (Plain Text or Data URL) below:

PUT /rest/v1/files/sd/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json
Content-Type: application/json
Content-Length: 196

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

Plain Text Request Body

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": {
        "fileUploadPath": "/sd",
        "files": [
            {
                "fileName": "test.txt",
                "fileContents": "Lorem Ipsum",
                "fileType": "text/plain"
            }
        ]
    }
}

Data URL Request Body

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

{
    "data": {
        "fileUploadPath": "/sd",
        "files": [
            {
                "fileName": "image.png",
                "fileContents": "data:image/png;base64,DQpJbnRlcmZh.....",
                "fileType": "image/png"
            }
        ]
    }
}

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 in the path (which should include the file name)

Segment

path string: The path to the file (for example, /sd)

Request Example

POST /rest/v1/files/sd/test.txt/?destinationType=player&destinationName={{deviceSerial} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json
Content-Type: application/json
Content-Length: 57

This is the example request body:

{
    "data": {
        "name": "newname.txt"
    }
}

Response Body

The player will return a success or error message.

DELETE /files/{:path}/

Deletes a file from the player storage

Segment

path string: The path to the file (for example,/sd)

Request Example

DELETE /rest/v1/files/sd/test.txt/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json

Response Body

The player will return a success or error message.

DELETE /storage/{:device_name}/

Reformats the specified storage device

You must disable the autorun before reformatting the SD card on your device. To disable the autorun, use the PUT /v1/control/reboot with body parameter { “autorun”:”disable” }, as described in this section. This can also be done in the local DWS Diagnostics tab.

Segment

device_name string: The specified storage device (see this page for a list of available devices)

Request Body Parameters

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

Request Example

DELETE /rest/v1/storage/sd/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json
Content-Type: application/json
Content-Length: 49

This is the example request body:

{
    "data": {
        "fs": "exfat"
    }
}

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:

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.
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.
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.
The player reboots, fetches the setup package from B-Deploy, and re-provisions itself.

Request Example

GET /rest/v1/reprovision/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json

Response Body

success bool: True means that the operation succeeded and the player will reboot. False means that the operation failed.

Keys related to setup

- inp (inherit network properties)
- networkjson (network settings in json format - setup version v3)
- modem_json (default settings for modem configuration in json format)

- wifi (use wireless)
- ss (wifi ssid)
- pp (wifi passphrase)

The first network interface, either ethernet or WiFi:
- dhcp (use dhcp)
- sip (static ip address)
- sm (subnet mask)
- gw (gateway)
- dns1 (first dns)
- dns2 (second dns)
- dns3 (third dns)

The second network interface, either ethernet or WiFi:
- dhcp2
- sip2
- sm2
- gw2
- dns12
- dns22
- dns32

- ncp (wired connection priority)
- ncp2 (wireless connection priority)

- up (use proxy)
- ps (proxy server url)
- bph (proxy bypass list)

- ts (time servers list)

Rate limits for the first network interface, ethernet or WiFi:
- rlmid (rate limit mode during initial downloads)
- rlrid (rate limit value during initial downloads)
- rlmow (rate limit mode outside download window)
- rlrow (rate limit value outside download window)
- rlmiw (rate limit mode inside download window)
- rlriw (rate limit value inside download window)

Rate limits for the second network interface, ethernet or WiFi:
- rlmid2
- rlrid2
- rlmow2
- rlrow2
- rlmiw2
- rlriw2

Enabled flag values for the ethernet interface:
- cwr (Content transfers enabled)
- twr (Text feed transfers enabled)
- mwr (Media feed transfers enabled)
- hwr (Health transfers enabled)
- lwr (Log upload transfers enabled)

Enabled flag values for the WiFi interface:
- cwf
- twf
- mwf
- hwf
- lwf

if vlanids = 25
- usedhcp_vlan_25
- staticipaddress_vlan_25
- subnetmask_vlan_25
- gateway_vlan_25
- dns1_vlan_25
- dns2_vlan_25
- dns3_vlan_25

POST /snapshot/

Takes a screenshot of the current screen contents and saves it to storage. See Remote DWS APIs#RequestMessageFormat for the Query String Parameters.

Request Example

POST /rest/v1/snapshot/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}

Response Body

remoteSnapshotThumbnail string: A snapshot image thumbnail in Base64 format
filename string: The name and path of the snapshot image file. Call GET /file/{:path} to retrieve the full-resolution image.
timestamp string: The date and time the snapshot was taken. The date/time is formatted as "yyyy-mm-dd hh:mm:ss <timezone>".

GET /health/

Retrieves the current status of the player. Currently, this endpoint is only used to determine if a player can respond to a WebSockets request; it cannot determine the error state of a player.

Request Example

GET /rest/v1/health/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json

Response Body

status string: The player status. The only possible value is "active".
statusTime string: The date and time the player responded to the status request. The date/time is formatted as "yyyy-mm-dd hh:mm:ss <timezone>".

PUT /custom/

Sends custom data to the player. The player in turn sends the data as a message (in JSON string format) on UDP port 5000, which can then be captured by the autorun.brs or a JavaScript application on the player.

Request Body

command string: The custom data to send
returnImmediately bool: A flag specifying whether the server should respond to the PUT request immediately (true) or wait on a response to the UDP message from the BrightScript/JavaScript application (false).

Request Example

PUT /rest/v1/custom/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json
Content-Type: application/json
Content-Length: 89

This is the example request body:

{
    "data": {
        "command": "next",
        "returnImmediately": true
    }
}

Response Body

If the returnImmediately property is true, the server will return a success or error message. If the property is false, the server will wait for a response from UDP port 5000 on the player and send it as the response to the PUT request.

GET /download-firmware/

Instructs the player to download and apply a firmware update.

Query String Parameter

url string: The public URL for downloading the firmware-update file.

Request Example

GET /rest/v1/download-firmware/?url=https://bsncloud.s3.amazonaws.com/public/cobra-9.0.110-update.bsfw&destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json

Response Body

success bool: A flag indicating whether the download was successful
reboot bool: A flag indicating whether the player will reboot when applying a firmware update