Remote DWS Endpoints - registry APIs

PUT  /time/ 

Sets the date/time on the player

Request Body Parameters

• 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

This is the example request body:

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

Request Example

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:

  • 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

Segments

• connector: The current value is always hdmi

• device: This value in /video/ URLs is currently 0 for single-output Series 5 players and all Series 4 and older players. The value can be 0-3 for the XC4055, which has multiple outputs, and 0 or 1 for the XC2055.

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

Segments

• connector: The current value is always hdmi

• device: This value in /video/ URLs is currently 0 for single-output Series 5 players and all Series 4 and older players. The value can be 0-3 for the XC4055, which has multiple outputs, and 0 or 1 for the XC2055.

Request Example

Response Body

• result string: The EDID string result

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

Retrieves the power status of the monitor connected to the player (as reported over EDID)

Segments

• connector: The current value is always hdmi

• device: This value in /video/ URLs is currently 0 for single-output Series 5 players and all Series 4 and older players. The value can be 0-3 for the XC4055, which has multiple outputs, and 0 or 1 for the XC2055.

Request Example

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 (for example, 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)

Segments

• connector: The current value is always hdmi

• device: This value in /video/ URLs is currently 0 for single-output Series 5 players and all Series 4 and older players. The value can be 0-3 for the XC4055, which has multiple outputs, and 0 or 1 for the XC2055.

Request Body Parameters

• enabled bool:  Whether or not power save is enabled 

Request Example

This is the example request body:

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

Segments

• connector: The current value is always hdmi

• device: This value in /video/ URLs is currently 0 for single-output Series 5 players and all Series 4 and older players. The value can be 0-3 for the XC4055, which has multiple outputs, and 0 or 1 for the XC2055.

Request Example

Response Body

Returns an array of video mode objects, each of which contain the following parameters:

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

• colorDepth string: The color depth of the video signal

• colorSpace string: The color space of the video signal

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

• frequency int: The frame rate of the video output

• 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

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

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

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

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

Retrieves the current video mode on the specified video output

Segments

• connector: The current value is always hdmi

• device: This value in /video/ URLs is currently 0 for single-output Series 5 players and all Series 4 and older players. The value can be 0-3 for the XC4055, which has multiple outputs, and 0 or 1 for the XC2055.

Query String Parameters

Each of these parameters delivers a different mode value:

• best int optional: If set to 1, this returns the best mode

• active int optional: If set to 1, this returns the active mode

• configured int optional: If set to 1, this returns the configured mode

Request Examples

Response Body

• isAutoMode bool: Whether the mode is set to “auto”

• name string: The name of the video mode. Same as mode.modeName below.

• width string: The width value of the video mode.

• height string: The height value of the video mode.

• frames string: The frame rate value of the video mode.

• scan string: The scan character value of the video mode.

• mode object: The currently configured video mode on the video output with following parameters -

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

  • colorDepth string: The color depth of the video signal

  • colorSpace string: The color space of the video signal

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

  • frequency int: The frame rate of the video output

  • 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

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

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

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

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

Changes the video mode on the player

Segments

• connector: The current value is always hdmi

• device: This value in /video/ URLs is currently 0 for single-output Series 5 players and all Series 4 and older players. The value can be 0-3 for the XC4055, which has multiple outputs, and 0 or 1 for the XC2055.

Request Body Parameters

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

This is the example request body:

Response Body

The server will return a success or error message. A successful response will almost always cause a reboot which will be indicated in the response.

• resultobject: The response object.

  • successbool: Whether or not the operation was successful

  • rebootbool: Whether or not the player is rebooting

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.

Request Example

Response Body

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

GET  /crash-dump/ 

Retrieves the crash dump from the player

Request Example

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 that contain the following entries:

    • fileName string: The name of the file. You can use this field to download the file later using GET /v1/files/sd/{{filename}}?contents.

    • 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 Parameters

• 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

Request Example (Crash Report)

This is the example request body:

Request Example (Factory Reset)

This is the example request body:

Request Example (Disable Autorun)

This is the example request body:

Response Body

The server will return a success or error message. A successful response will almost always cause a reboot which will be indicated in the response.

• resultobject: The response object

  • successbool: Whether or not the operation was successful

  • rebootbool: Whether or not the player is rebooting

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

Request Example

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 Parameters

• 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

This is the example request body:

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

Request Example

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

This is the example request body:

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

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

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:

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 URL Request Body

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

Segment

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

Request Example

This is the example request body:

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

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

This is the example request body:

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.

Request Example

Response Body

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

GET /diagnostics/ 

Runs network diagnostics on the player

Request Example

Response Body

• ethernet string:

  • diagnosis string: Indicates if this type of interface is present

  • log object[ ]: This contains the diagnostic results for the ethernet interface. It has fields for name, pass, and result.

    • name string:  The name of the diagnostic test

    • pass bool: Indicates whether the test passed or not

    • result string: The actual value for the diagnostic tests like checking type and ping.

  • ok bool: If diagnostics were run on the interface or not.

• wifi string:

  • diagnosis string: Indicates if this type of interface is present

  • log object[ ]: This contains the diagnostic results for the wifi interface. It has fields for name, pass, and result.

    • name string:  The name of the diagnostic test

    • pass bool: Indicates whether the test passed or not

    • result string: The actual value for the diagnostic tests like checking type and ping.

  • ok bool: If diagnostics were run on the interface or not.

• modem string:

  • diagnosis string: Indicates if this type of interface is present

  • log object[ ]: This contains the diagnostic results for the modem interface. It has fields for name, pass, and result.

    • name string:  The name of the diagnostic test

    • pass bool: Indicates whether the test passed or not

    • result string: The actual value for the diagnostic tests like checking type and ping.

  • ok bool: If diagnostics were run on the interface or not.

• internet string:

  • diagnosis string: Indicates if this type of interface is present

  • log object[ ]: This contains the diagnostic results for the internet connectivity. It has fields for info, name, pass, and result.

    • info string: Returns DNS server info

    • name string:  Checks DNS servers and internet connectivity

    • pass bool: Indicates whether the test passed or not

    • result string: The actual value for the diagnostic tests like checking type and ping. 

  • ok bool: If diagnostics were run on the interface or not.

GET /diagnostics/dns-lookup/{:domain_name}/ 

Tests name resolution on the specified DNS address

Segment

• domain_name: The DNS address (for example, google.com)

Request Example

Response Body

The player queries each DNS field separately, then collects returned data into the records object and returned errors into the errorList object. The following DNS fields are queried: "ipv4", "ipv6", "cname", "mx", "service", "text".

• records object

  • ipv4 string[ ]

  • ipv6 string[ ]

  • text string[ ]

  • mx object[ ]

    • exchange string

    • priority int

• server_test object

  • tcp object

    • made int:  The total number of DNS requests made

    • pass int: The total number of requests that passed

    • fail int: The total number of requests that failed.

    • timeout int: The total number of requests that timed out.

    • mismatch int

  • udp object

    • made int:  The total number of DNS requests made

    • pass int: The total number of requests that passed

    • fail int: The total number of requests that failed.

    • timeout int: The total number of requests that timed out.

    • mismatch int

• errorList object[ ]

  • field string

  • err object

    • errno string: Error number (usually the same value as code)

    • code string: Error code number

    • syscall string

    • hostname string: The value passed in the URL

GET /diagnostics/ping/{:domain_name}/ 

Requests the player to ping the specified IP or DNS address on its local network. This call can take over 10 seconds to return.

Segment

• domain_name: The specified IP or DNS address

Request Example

Response Body

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

• response object:

  • hostname string: The value that you passed in the URL

  • results object

    • ipv4 object[ ]

      • address string: The IPv4 address

      • results object

        • received int: The number of packets received

        • stats object

          • average int: The average time for the packet to return

          • quickest int: The quickest time for packet to return

          • slowest int: The slowest time for the packet to return

          • units int: The time units (usually microseconds)

        • transmitted int: The number of packets transmitted

    • ipv6 object[ ]

      • interface string

      • source string

      • address string: The IPv6 address

      • results object

        • received int:  The number of packets received

        • transmitted int: The number of packets transmitted

GET /diagnostics/trace-route/{:domain_name}/ 

Requests the player to perform a standard trace-route diagnostic on the specified IP or DNS address. This call can take several minutes to return.

Segment

• domain_name: The specified IP or DNS address

Query String Parameter

resolveAddress bool: Specifies whether the IP or DNS address should be resolved or not

Request Example

Response Body

• address string

• results object

  • output string[ ]: Returns the trace route output information in text format

  • protocol string: The IP protocol, for example, "ipv4"

  • route object[ ]:

    • hop int

    • servers object

      • address string: The address to which the trace route request is made

      • hostname string

      • stats object[ ]

        • reachable string

        • time string: The time required for the trace route request to return

        • units string: The time units (usually in milliseconds)

GET /diagnostics/network-configuration/{:interface}/ 

Retrieves information about network-interface settings on the player

Segment

• interface: The network interface. Possible names include eth0, wlan0, and modem.

Request Example

Response Body

• text string: The network configuration information in plain-text form

• output Output: The network configuration information as a JSON object:

  • interfaces Interface[ ]: An array of Interface objects representing network interfaces:

    • name string: The interface name (for example, "eth0")

    • errors  Error[ ]: An array of error messages associated with the interface

    • params Param[ ]: An array of Param objects representing parameters associated with the network interface. Each Param interface has the following entries:

      • name string: The property name (e.g. "MAC")

      • value string: The property value (e.g. "90:ac:3f:0b:d2:88")

  • host Info[ ]: An array of Info objects providing network host information. Each object can have the following entries:

    • errors Error[ ]: An array of error messages associated with the network host

    • params Param[ ]: An array of Param objects representing parameters associated with the network host 

  • bsn Info[ ]: An array of Info objects providing information about BSN communication. 

  • other Info[ ]: An array of Info objects providing information miscellaneous network information.

• caCertificate string: The contents of a CA certificate file in text form (i.e. a "pem" file).

• clientCertificate bool: A flag indicating whether the player is using a client certificate

• clientIdentifier string: The DHCP client identifier for the network interface

• dnsServerList string[ ]:  An IP address list of the DNS servers

• domain string: The domain name for the network interface

• eapTlsOptions string: A string containing EAP-specific options

• enabledProtocolList string[ ]: An array of enabled IP protocols. Currently supported values are "IPv4" and "IPv6".

• identity string: The RADIUS identity

• ipAddressList string[ ]: The IP addresses assigned to the player

• inboundShaperRate int: The bandwidth limit for inbound traffic in bits per second. A value of -1 specifies the default bandwidth limit, and a value of 0 specifies no bandwidth limit (these two settings are functionally the same).

• metric int:  The routing metric for the default gateway on the interface. Routes with lower metrics are preferred over routes with higher metrics.

• mtu int: The maximum transmission unit (MTU) for the network interface in bytes

• privateKey string: The private key for authentication

• vlanIdList int[ ]: An array of VLAN IDs that are supported on the parent network interface

• securityMode string: Security mode for authentication

• securityMode string

GET /diagnostics/network-neighborhood/ 

Retrieves information about the current network neighborhood of the player

Request Example

Response Body