Status API

Introduction

The Status API is usefull for getting the player's current status with information such as: identification details, operating status, device stats, file errors, time and network configuration, screen display settings, storage details, content pull scheduling settings etc. All these details are found on different pages within Control Center – the Status API returns them in XML format . A snapshot of the content being rendered can also be requested.

Notes:

The configuration backup feature should be used to retrieve the current configuration.
RPC API should be used to query the status of the device regularly – note however that generating the status uses some CPU power on the device and might interfere with the smoothness of the rendering.

Authentication

The access to the Status API is protected. Authentication is done using the credentials of users defined in Control Center, with "monitoring" or "admin" rights.

Player	User rights	Authentication
HMP400/W, HMP350, HMP300, iBX410/W, iBX440	monitoring, admin	HTTP Basic, TLS-SRP
DiVA	admin	HTTP Basic, TLS-SRP
HMP200, HMP130, HMP100	monitoring, admin	HTTP Basic

Using AJAX

AJAX calls can be employed within web pages to get information from the Status API. If the script is loaded from the player content server, then the authorization is done when logging onto the player. If the script is located on another host (CORS), then you need to manually enter the credentials in the browser's pop-up dialog when asked or include the credentials through the "Authorization" header (see the example below).

To protect the player against CSRF when using CORS, the spx-api-key query string parameter must be appended to the end-point and set to the API Key value configured on that player (from Control Center ⇾ Advanced Applications ⇾ APIs Security, or by using the <rpc-api-key> configuration tag).

Notes:

CORS (cross-origin resource sharing) and CSRF (Cross-site request forgery) protection are supported for the Status API starting with DSOS 4.5.3.
It is possible to configure manually the same API key for different devices, so that the same script can be used for any of them.

Endpoints

The Status API base URL is http(s)://Player_address/status with two endpoints: /info and /snapshot.

Note:

HTTP Secure is not avaialble on legacy players.

info

GEThttp(s)://Player_address/status/info

Returns an XML response containing the current status of the player.

GEThttp(s)://Player_address/status/info?offset=-HH:mm:ss GEThttp(s)://Player_address/status/info?offset=date

Returns an extended XML response containing the current status of the player and the evolution of the temperature and rendering stats of the player. The offset parameter can be a negative time period (-HH:mm:ss) or a date. Note that the maximum period is 24h and no more than 100 entries are retrieved, whichever comes first.

Response

The result is an XML document having the following structure:

<?xml version="1.0"?>
<status xmlns="http://www.spinetix.com/namespace/1.0/spxstatus" xmlns:spxs="http://www.spinetix.com/namespace/1.0/spxstatus" spxs:version="5">
    <device>...</device>
    <status>...</status>
    <stats>
        <sample>...</sample>
    </stats>
    <fileErrors>...</fileErrors>
    <time>...</time>
    <network>...</network>
    <screen>...</screen>
    <storage>...</storage>
    <storagedevices>...</storagedevices>
    <version>...</version>
    <uploader>...</uploader>
    <license>...</license>
</status>

where:

<device> Contains information about the device.

<name> → model name,
<serial> → serial number,
<ethmac> → MAC address,
<revision> → hardware revision.

<status> Contains information about the operating status.

<safemode> → the Safe mode status (on / off).
<firmware> → the firmware update status, from the following:
complete - the update was complete, or the update check does not detect any available updates.

available - there are updates available.

pending - some packages have been updated, but a new run is needed to complete the update process.
<bootid> → an unique boot ID,
<uptime> → device uptime,
<bootReason> → the reason of the last boot,
<temp> → device internal temperature (this is not available on HMP130 / HMP100).

<stats><sample> Current device stats - see more details about these on player.log section.

<time> → the time of the stats sampling,
<render> → the total rendering time,
<pictures> → the number of rendered pictures (frames) within the sampling period (usually 1 min).
<usage> → usage stats,
<peak> → peak stats,
<buffers> → buffers stats,
<dropFPS> → FPS drop stats,
<dropPeak> → peak drop stats.

<fileErrors> Contains information about file errors.

<error> → file error details (time, code, source, description).

<time>

<date> → the current date and time
<timezone> → the configured time zone.
<GMTOffset> → the GMT offset of the configured time zone.

<network> Contains information about the network configuration.

<deviceName> → device name,
<hostname> → device hostname,
<ip> →device IPv4 address,
<prefixLength>
<interface> → the network interface type (Ethernet, WLAN, 3G)
<ipv6><ipv6addr> →IPv6 addresses,
<secondaryAddresses><address> → the Ethernet address details when the player is configured for Wi-Fi.
<configuration>
- <interface> → interface type (ethernet, wlan),
- <method> → configuration type (dhcp, static).

<screen> Contains information about the screen settings.

<screenID> → Multiscreen ID,
<snapshotURI> → URI to get the snapshot,
<resolutionWidth>, <resolutionHeight> → resolution width and height, or unknown
<verticalRefresh> → vertical refresh, or unknown
<aspectRatio> → aspect ratio, or unknown
<overscanPercent> → overscan percent,
<orientation> → display orientation,
<powerSave> → display power save (on / off),
<audio><mute> → audio status (on / off),
<display> → information about the display(s) connected to the player’s video output(s):
- <id> → video connector ID (e.g., “card0-DP-1”)
- <type> → the type of the display connector (HDMI, DVI, DisplayPort Alt Mod)
- <powered> → the status of the display (on | off | unknown)
- <pm_supported> → 0 or 1, tells if power management is supported with the currently attached display; this is a most-likely guess since it is not possible to know for sure
- <cec_capable> → 0 or 1, tells if the output has a CEC adapter or not. Added in firmware 4.6.0.

<storage> Contains information about the storage information.

<content> → information about the storage space of the Local Storage partition,
<system> → information about the storage space of the System partition.

<storagedevices> Contains information about the storage device information.

<storagedevice>
- <location>
- <size>
- <unit>

<version>

<firmware> → firmware version and build number.
<bootloader><version> → bootloader version.

<uploader> Content pull scheduling information.

<mode> → the content Pull mode, which can be:
"Disabled" - no content pull,

"Manual" - pull from a web server,

"Automatic" - pull according to an ICS file uploaded on the device,

"Server" - pull according to a remote ICS file.
<projectSource>, <projectTime> → project source URI and time of pull when mode is manual.
<calendar> → calendar URI when mode is server.

Applies to HMP400, HMP400W, and 3rd-party players.

<license> Contains data related to the DSOS license. Added in firmware 4.7.6.

<checkDate> → the date & time of the check
<features> → license feature details (name, source, etc.), when a DSOS license is currently activated on the player.

Extended response

When the offset parameter is used, the XML response includes more rendering statistics (up to 100 <sample> entries are added under <stats>), as well as the evolution of the player's internal temperature (also capped at 100 entries):

<tempHistory><sample> Contains information about the device temperature.

<time> → the time of the stats sampling,
<C> → the temperature in degree Celsius,
<F> → the temperature in degree Fahrenheit.

snapshot

GEThttp(s)://Player_address/status/snapshot

Returns a JPEG image representing the snapshot of the content being rendered.