Status API

From SpinetiX Support Wiki

Jump to: navigation, search

Introduction

As the name implies, 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 should be used to query the status of the device in a regular manner - note however that generating the status uses some CPU power on the device and might interfere with the smoothness of the rendering.

Authentication

Authentication is done using the credentials of users defined in Control Center, with monitoring or admin rights.

Player User rights Authentication
HMP350, HMP300 monitoring, admin HTTP Basic, TLS-SRP
DiVA admin HTTP Basic, TLS-SRP
HMP200, HMP130, HMP100 monitoring, admin HTTP Basic

Endpoints

The Status API offers two endpoints:

Note Note:
HTTP Secure can only be used with HMP350, HMP300, and DiVA players.

info

  • GET /status/info
  • GET /status/info?offset=-HH:mm:ss
  • GET /status/info?offset=date

Returns an XML response containing the current status of the player. 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.

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><storagedevice> Contains information about the storage device information.
    • <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.

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

GET /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 29 August 2018, at 13:00.