Configuration API

From SpinetiX Support Wiki

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

Summary information and/or updates to the documentation can be found on this page.

Introduction

The Configuration API allows modifying different configuration settings of the SpinetiX players. It uses XML (Extensible Markup Language) as data format and defines the syntax used to modify different configuration settings on the player or to trigger different actions, like a player reboot.

It is intended for developers looking for means to modify a batch of configuration settings of the SpinetiX players, instead of changing them one by one from the Control Center interface.

It was introduced in firmware 2.2.1, when the configuration backup & restore feature was added in Control Center as a convenient way of saving a full configuration of the player for later use - for instance, to quickly restore it after a reset to factory default settings. The configuration file inside the player backup is generated according to the Configuration API rules. Additionally, the RPC API was extended in firmware 2.2.3 with two commands for getting or setting the player configuration – both are following the Configuration API rules. Further changes and improvements of the Configuration API were added in subsequent firmware releases.

How to use this API

There are two ways to use this API to configure a player:

Both require using a configuration string in XML format, with a certain structure and containing one or more commands / tags encapsulated within a <configuration> element.

XML configuration string

The XML configuration string can reflect a full configuration of the player (as it is the case when the configuration backup is generated from Control Center) or it can update only a limited number of settings (the missing ones will keep their current value).

The XML configuration string can be used either as the content of the config.xml file (which gets included into a configuration backup) or as the value of the xmlconfig parameter of the set_config RPC command (in this case make sure to properly encode the XML string).

Structure

The XML configuration string must have the following structure:

<?xml version="1.0"?>
<configuration version="n.n" compatible="n.n">
    <command-1>...</command-1>
    ...
    <command-n>...</command-n>
</configuration>

The indent of the inner elements is just for readability.

<configuration>

The <configuration> element is required and encapsulates one or more configuration tags. It has the following attributes:

  • version (required)
    The value (“n.n”) depends on the player firmware, as following:
    • "2.1" for firmware versions 4.2.x and above.
    • "2.0" for firmware versions 4.0.x and 4.1.x.
    • "1.2" for firmware versions 3.2.x (two new tags added).
    • "1.1" for firmware versions 3.0.x and 3.1.x (the syntax of two existing tags changed).
    • "1.0" for firmware versions below 3.0.0.
  • compatible (optional)
    Many configuration tags are compatible between configuration versions, as their syntax hasn’t changed, so the “compatible” attribute can be used to create a configuration string accepted by players using different firmware versions. Nevertheless, this implies verifying that the configuration tags are using the same syntax regardless of the player model, so it might be easier just to create separate configuration strings for 4.x firmware versions (i.e., HMP350, HMP300, DiVA players) and 3.x (i.e., HMP200, HMP130, HMP100 players).

<command-1>…<command-n>

The <configuration> element should contain one or more "command" XML elements descendants, which can either apply a setting onto the player or trigger an action, like a reboot.

Parameters

Some configuration tags don't require any parameter - for instance, to configure the player to use DHCP, write:

<ethernet-dhcp/>

If the configuration tag requires one parameter, it is usually provided within the text content of the element - for instance, to change the time zone setting, a name is specified within the text content of the element:

<timezone>Europe/Zurich</timezone>

If it requires more parameters, these are usually provided as inner XML elements - for instance, to set a fixed IP address, several parameters are needed, each being provided as a separate XML elements under the ethernet-static tag, as following:

<ethernet-static>
    <address>192.168.1.10</address>
    <netmask>255.255.255.0</netmask>
    <gateway>192.168.1.1</gateway>
    <dns>192.168.1.1</dns>
</ethernet-static>

Execution order

The configuration tags are applied in the order provided - since different tags might affect the same player setting, the order in which they are provided influences the result.

  • For instance the <ethernet-dhcp/> tag will set the player to DHCP, whereas the <ethernet-static> tag will set it to use a fixed IP address. If both tags are present in the XML configuration string, the last one will be taken into consideration.
  • The only exception is the <reboot/> command which can appear anywhere in the XML configuration string, but will only be applied once all commands have been executed.

Action tags

Further details about each action tag can be found within the technical documentation.

Tag Component Added in Notes
certificates-reset security 3.0.3 Remove all SSL/TLS certificates that are present on the device.
credential-reset security 2.2.1 Remove all previous credentials on the device.
enable-arya player 4.4.0 Enable the ARYA mode. Applies to DiVA.
live-source-reset content 4.0.0 Remove all live sources from the player. Applies to HMP350 and HMP300.
protocol-file-reset serial 3.1.0 Remove all FSM files that are present on the device. Doesn't apply to DiVA.
reboot player 2.2.1 Instruct the device to reboot once all the settings have been applied successfully.
regenerate-secret-key security 4.2.0 Force the player to re-generate a new secret key and clear all previously set passphrase.
reset-arya player 4.4.0 Reset the ARYA mode, allowing the user to (re)select between DiVA built-in interface or ARYA cloud interface for content managing. Applies to DiVA.
reset-cache content 4.4.0 Reset the network cache. Applies to HMP350 and HMP300.
reset-content content 4.4.0 Reset all the content on the player: the published content, the content created within the web interface and the web storage data. Applies to HMP350 and HMP300.
reset-log content 4.4.0 Reset the player logs. Applies to HMP350 and HMP300.
reset-ntp content 4.4.0 Reset the internal clock calibration data. Applies to HMP350 and HMP300.
reset-published-content content 4.4.0 Reset the content published on the player. Applies to HMP350 and HMP300.
reset-webstorage content 4.4.0 Reset the web storage data. Applies to HMP350 and HMP300.
scheduled-download-reset content 4.0.0 Remove all scheduled downloads from the player. Applies to HMP350 and HMP300.
server-certificates-reset security 4.2.0 Remove all server certificates that are present on the device.
user-reset security 4.0.0 Remove all configured users (except the admin user).

Configuration tags

Further details about each configuration tag can be found within the technical documentation.

Tag Component Added in Notes
accepts-events interactivity 2.2.1 Set whether the player accepts interactive events from the USB connector . Doesn't apply to DiVA.
active-certificate network 4.2.0 Activate one of the previously uploaded server certificate.
audio-output player 4.3.0 Set the audio output to either HMDI or line-out.
audio-power-save player 3.1.0 Set whether the player shall output audio when the screen is in power save.
bonjour-enabled network 4.2.3 Set whether Bonjour service (discovery and name resolution) is enabled on the player.
bonjour-discovery-enabled network 4.2.2 Set whether Bonjour discovery is enabled in the player.
certificate security 3.0.0 Add SSL/TLS certificate to the device. Last modified in 4.2.0 firmware.
cockpit player 3.2.0 Enable Cockpit monitoring on the device.
cockpit-disabled player 3.2.0 Disable Cockpit monitoring on the device.
com-port-settings serial 2.2.1 Set the serial port settings or reset them to their default values. Doesn't apply to DiVA.
credential security 2.2.1 Add credential to the device.
disable-secondary-network-port network 4.2.0 Set whether the secondary network port on the HMP350 is disabled.
display-custom-video-mode display 2.2.1 Set a custom video mode for the display. Doesn't apply to HMP300 and DiVA.
display-orientation display 2.2.1 Set the orientation of the display.
display-power-save player 2.2.1 Enable display power saving.
display-power-schedule player 2.2.1 Set or remove a fixed display power saving schedule.
display-video-mode display 2.2.1 Set a standard video mode for the display.
device-name network 2.2.1 Set the device name to be used by the network discovery protocols.
dns-automatic network 4.2.3 Set a DHCP assigned DNS server address on the player.
dns-manual network 4.2.3 Set a fixed set of DNS servers on the player.
enable-audio player 2.2.1 Enables or disables the player audio output.
ethernet-dhcp network 2.2.1 Set a DHCP assigned IP address on the player.
ethernet-static network 2.2.1 Set a fixed IP address on the player.
firmware-update-auto player 2.2.1 Set the hour for daily firmware update check or disable this feature. Doesn't apply to DiVA.
firmware-update-uri player 2.2.1 Set the URI of the firmware update repository. Doesn't apply to DiVA.
hdmi-link-type display 3.0.3 Set the HDMI signal type.
http-server-security-access security 4.2.0 Set whether the player web server shall accept unsecure HTTP connection.
https-validate-certificates security 2.2.5 Set whether the player shall accept only trusted HTTPS certificates.
live-source-add content 4.0.0 Add a live source onto the player. Applies to HMP350 and HMP300.
maximum-latency rendering 2.2.1 Set the rendering latency of the player. Doesn't apply to DiVA.
modem-3g-advanced network 2.2.1 Set the player to use 3G modem as network connection using advanced settings. Doesn't apply to HMP300 and DiVA.
modem-3g-simple network 2.2.1 Set the player to use 3G modem as network connection using simplified settings. Doesn't apply to HMP300 and DiVA.
network-api-enabled network, interactivity 2.2.1 Set whether the Network API is enabled. Doesn't apply to HMP300 and DiVA.
network-api-port network 2.2.1 Set the port used by the Network API to listen to incoming connections. Doesn't apply to HMP300 and DiVA.
network-watchdog network 2.2.1 Set the network watchdog parameters. Doesn't apply to DiVA.
overscan-percentage display 2.2.1 Set the percentage of overscan done by the screen attached to the player.
passphrase security 4.2.0 Set or clear the passphrase to be used to encode the passwords and other secrets present in the backup.
protocol-disabled serial 2.2.1 Disable the usage of FSM protocol file. Doesn't apply to DiVA.
protocol-file serial 2.2.1 Select a custom FSM file as the active protocol file of the device. Last modified in 3.0.0 firmware. Doesn't apply to DiVA.
protocol-system serial 2.2.1 Enable the usage of one of the internal protocol files available in the device. Last modified in 3.0.0 firmware. Doesn't apply to DiVA.
proxy network 2.2.1 Set the proxy settings for Internet access.
pull-mode-disabled content 2.2.1 Disable Pull Mode. Doesn't apply to DiVA.
pull-mode-file content 2.2.1 Configure Pull Mode settings using an ICS file embedded into the configuration file. Doesn't apply to DiVA.
pull-mode-remote content 2.2.1 Configure Pull Mode settings using an ICS file located on a remote server. Doesn't apply to DiVA.
pull-mode-static content 2.2.1 Set a static Pull Mode configuration. Last modified in 4.0.0 firmware. Doesn't apply to DiVA.
pullmode-logs-level player 4.1.0 Set the logging level for the uploader.log (used by Pull Mode). To be used only for debugging purpose.
reduce-interactive-latency interactivity 2.2.1 Configure the player to reduce the rendering latency to 60 ms when interactive events are received. Doesn't apply to DiVA.
rpc-api-key security 4.0.0 Set or clear the RPC API key. Doesn't apply to HMP300 and DiVA.
scheduled-download-add content 4.0.0 Add a scheduled download onto the player. Applies to HMP350 and HMP300.
screen-aspect-ratio display 2.2.1 Set the aspect ratio of the screen. Doesn't apply to DiVA.
screen-id content 2.2.1 Set the screen ID for multiscreen content. Doesn't apply to HMP300 and DiVA.
secure-admin security 4.0.0 Set whether remote actions assigned to the admin role, such as executing RPC commands, require credentials (user and password). Applies to HMP350, HMP300.
secure-content security 4.0.0 Set whether remote actions assigned to the content authoring role require credentials (user and password). Applies to HMP350, HMP300.
secure-monitoring security 4.0.0 Set whether remote actions assigned to the monitoring role require credentials (user and password). Applies to HMP350, HMP300.
server-certificate security 4.2.0 Add an HTTP server certificate to the device. Last modified in 4.2.2 firmware.
shutdown-temperature player 2.2.1 Set the automatic shutdown temperature. Doesn't apply to HMP130 and HMP100.
snmp-all network 2.2.1 Enable access to the SNMP service from any host. Doesn't apply to DiVA.
snmp-limited network 2.2.1 Enable connections to the SNMP service from remote hosts if they are within the given address range. Doesn't apply to DiVA.
snmp-local network 2.2.1 Disable SNMP connections outside the player. Doesn't apply to DiVA.
snmp-rocommunity network 2.2.1 Configure the name of the SNMP read-only community. Doesn't apply to DiVA.
splash content 3.0.0 Set the splash images used by the device when booting, restarting or updating the firmware.
ssdp-upnp-enabled network 4.1.0 Set whether SSDP / UPnP discovery is enabled in the player.
touchscreen interactivity 2.2.1 Set the calibration parameters of the connected touchscreen. Doesn't apply to DiVA.
time-manual player 2.2.1 Set a manual time onto the player.
time-ntp player 2.2.1 Configure one or more NTP servers as time source. Doesn't apply to DiVA.
time-ntp-restore player 4.0.0 Restore the default NTP configuration.
timezone player 2.2.1 Set the player time zone. The list of time zones accepted by the player can be found here - for more details about each time zone, see this page on Wikipedia.
underscan-supported display 2.2.1 Set whether the information returned by the TV screen concerning underscan should be used.
user security 2.2.1 Create a new user, update an existing user or remove an existing user. Last modified in 4.0.0 firmware.
vga-dc-offset display 2.2.4 Indicate that the VGA display connected to the player supports a DC voltage offset in the RGB signals. Applies to HMP200, HMP130, HMP100.
vga-power-mode player 2.2.1 Set whether the VGA output is on. Applies to HMP200, HMP130, HMP100.

Examples

1) The configuration string below sets the aspect ratio of the screen to 16:9 and its orientation to rotated right, enables the audio output, sets the device name to "office-screen" and forces a reboot to apply these changes. No other parameters are modified.

<?xml version="1.0"?>
<configuration version="1.2" compatible="2.0">
    <screen-aspect-ratio>16:9</screen-aspect-ratio>
    <display-orientation>horizontal</display-orientation>
    <display-orientation>rotateRight</display-orientation>
    <enable-audio>yes</enable-audio>
    <device-name>office-screen</device-name>
    <reboot/>
</configuration>

2) The configuration string below adds a daily Scheduled Download to retrieve the "School" sample project from SpinetiX demo server.

<?xml version="1.0"?>
<configuration version="2.1">
    <scheduled-download-reset/>
    <scheduled-download-add>
        <uri>http://demo.spinetix.com/sample_projects/School/spx-listing.xml</uri>
        <update>daily</update>
        <time>3:10</time>
    </scheduled-download-add>
</configuration>
This page was last modified on 10 December 2018, at 20:19.