Status API

From SpinetiX Support Wiki

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

Introduction

The Status API can be used to get the current status of the player, containing 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, HMP400W, HMP350, HMP300 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 can only be used with HMP350, HMP300, and DiVA 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 or 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.

XML response

The result is an XML document having the device information wrapped in a <status> element, containing the following children elements:

  • <device> Contains information about the device.
  • <status> Contains information about the operating status.
    • <safemode> = safe mode status (on / off).
    • <firmware> = firmware update status - can be one of 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> = 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> = current date and time
    • <timezone> = configured time zone.
    • <GMTOffset> = GMT offset of the configured time zone.
  • <network> Contains information about the network configuration.
    • <deviceName> device name,
    • <hostname> device hostname,
    • <ip> device IP,
    • <prefixLength>
    • <interface> = Ethernet or 3G,
    • <ipv6> IPv6 addresses,
    • <configuration>
      • <interface> = interface type,
      • <method> = dhcp or static.
  • <screen> Contains information about the screen display settings.
    • <screenID> = Multiscreen ID,
    • <snapshotURI> = snapshot URI,
    • <resolutionWidth>, <resolutionHeight> = resolution width and height,
    • <verticalRefresh> = vertical refresh,
    • <aspectRatio> = aspect ratio,
    • <overscanPercent> = overscan percent,
    • <orientation> = display orientation,
    • <powerSave> = display power save (on / off),
    • <audio><mute> = audio status (on / off),
    • <display> = display info (type, manufacturer, powered, link etc.).
  • <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> = array containing the list of features, or empty if no DSOS license is currently not activated on the player.

Extended XML response

An offset parameter can be added to get an extended XML response that includes the evolution of the temperature and rendering stats of the player; it 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.

When used, multiple <sample> entries are added under <stats> and the <tempHistory> element is added before the <stats> one. The latter has the following structure:

  • <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.
This page was last modified on 31 January 2023, at 19:55.