Status API

From SpinetiX Support Wiki

(Redirected from HMP Status API)
Jump to: navigation, search


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.

Note 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 CenterAdvanced Applications ⇾ APIs Security, or by using the <rpc-api-key> configuration tag).

Note Notes:

Endpoints

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

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


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

Note  
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.
Note Note:
Although the snapshot image can be generated as low as every 10 seconds, this process uses some CPU power and might interfere with the smoothness of the rendering. Therefore, the snapshot should not be requested very often – the minimum interval should be at least 60 seconds.

See also

This page was last modified on 20 May 2024, at 20:21.