Configuration API

From SpinetiX Support Wiki

Jump to: navigation, search
Configuration API Technical Documentation
Version: 7 (revision history)
Release date: May, 2024
Applies to: HMP400/W, HMP350, HMP300, DiVA, iBX410/W, iBX440, third-party players

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 like resetting the content, enabling capturing the HTTP traffic, or rebooting the player to apply the configuration changes.

The Configuration API 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 methods require using a configuration string in XML format, with a certain structure and containing one or more commands/tags encapsulated within a <configuration> element. This XML configuration string can be created within any text editor, either from scratch or starting from the config.xml file found inside the configuration backup generated by the player.

Note Note:
If you plan to use the RPC commands, then send a get_config command and check the result, which is a plain object containing an "xmlconfig" string of the complete configuration of the player.

Configuration file

A configuration file contains an XML configuration string composed of one or more commands/tags, encapsulated within a <configuration> element, to be executed by the player, as explained below. It can be created within any text editor, either from scratch or starting from the config.xml file found inside the configuration backup generated by the player.

The configuration file can be applied onto the player from Control Center – the file extension can be "xml", "cfg", "spx". If the player has been added into SpinetiX ARYA™, you can apply the configuration file from the "Players → Setup" page, by dragging & dropping it on top of the player's thumbnail.

Starting with DSOS release 4.5.1, the configuration file can be put on a USB stick and configure a player with it.

XML configuration string

The XML configuration string can reflect a full configuration of the player 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 a configuration file 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>
    <reboot/>
</configuration>

The indent of the inner elements is just for readability.

<configuration>

<configuration version="n.n" compatible="n.n">commands</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.2" for firmware versions 4.8.0 and above (added a new tag, modified three tags, and deprecated one tag)
    • "2.1" for firmware versions 4.2.0 - 4.7.x (added the passphrase)
    • "2.0" for firmware versions 4.0.0 - 4.1.2 (added new tags and removed some others that no longer apply)
    • "1.2" for firmware versions 3.2.0 - 3.4.5 (two new tags added)
    • "1.1" for firmware versions 3.0.0 - 3.1.1 (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>

This generic “command” element can either apply a setting onto the player or trigger an action, like removing the content published on the player. It is represented within the XML configuration string through an XML element, direct descendant of the <configuration> element.

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>

<reboot/>

This triggers a reboot of the player when at least one of the commands from the configuration file requires it, or there is a reboot pending following configuration changes not yet applied onto the player.

The tag can appear anywhere in the XML configuration string, but it is only executed at the end, after all the other commands have been verified and executed; in case of configuration errors, the player will not reboot.

If this tag is missing, then all the settings requiring reboot will not become effective until a manual reboot, or until another configuration having the reboot tag within is applied.

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.

Configuration tags

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

Tag Component Added in Mod. 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.
allow-usb-sources peripherals 2.2.5 4.7.4 Use external USB drives to store content. Doesn't apply to DiVA.
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.
canvas display 4.8.0 Set the canvas size, in pixels, for video output on multiple screens. Applies to iBX440.
capture peripherals 4.7.1 Configure one or more audio/video capture devices connected to the player through USB. Applies to HMP400/W.
certificate security 3.0.0 Add SSL/TLS certificate to the device. Last modified in 4.2.0 firmware.
certificates-reset security 3.0.3 Remove all SSL/TLS certificates that are present on the device.
clear-captures logs 4.5.0 Clear any capture files, both for stream and HTTP packets, present on the player. Doesn't apply to DiVA.
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 peripherals 2.2.1 3.1.0 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.
credential-reset security 2.2.1 Remove all previous credentials on the device.
disable-cloud network 4.5.0 Disable all communications with the SpinetiX cloud.
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 4.8.0 Set a custom video mode for the display. Doesn't apply to HMP300 and DiVA. Deprecated in 4.8.0.
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 4.6.1 Set or remove a fixed display power saving schedule.
display-video-mode display 2.2.1 4.8.0 Set a standard or custom 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.
echo-cancellation content 4.5.0 Enable or disable the WebRTC audio processing (echo cancelation) in HTML content. Applies to HMP400/W.
enable-arya player 4.4.0 Enable the ARYA mode. Applies to DiVA.
enable-audio player 2.2.1 Enables or disables the player audio output.
enable-cloud network 4.5.0 Enable communications with the SpinetiX cloud.
enable-USB-IO-API peripherals 3.0.0 Enable or disable the USB I/O API. Doesn't apply to DiVA.
encrypted-network-api-psk security 4.3.0 The encrypted pre-shared key generated by Control Center during backup. Doesn't apply to HMP300 and DiVA.
encrypted-webstorage-token security 4.6.3 The encrypted webstorage token generated by Control Center during backup. Doesn't apply to HMP300 and DiVA.
ethernet-dhcp network 2.2.1 Configure the player to use Ethernet for its network connection with a DHCP assigned address for its IPv4 configuration.
ethernet-static network 2.2.1 4.2.3 Configure the player to use Ethernet for its network connection with a fixed IPv4 address.
ethernet-v6-none network 4.2.3 Configure the player to not add any IPv6 address to the Ethernet interface, apart from the SLAAC (Stateless Address Auto-configuration) assigned addresses.
ethernet-v6-static network 4.2.3 Configure the player to add a fixed IPv6 address to the Ethernet interface.
features-check player 4.6.0 Check DSOS license features. Applies to HMP400/W.
firmware-update-auto player 2.2.1 4.4.2 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-capture-log logs 4.4.0 Enable capturing the HTTP traffic for the player. Applies to HMP350 and HMP400/W.
http-publish-secure-only network 4.3.0 Enables or disables allowing connections to the publish server over HTTPS only.
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.
license-file player 4.6.0 Add/remove a DSOS license of the player. Applies to HMP400/W.
live-source-add content 4.0.0 Add a live source onto the player. Applies to HMP350 and HMP300.
live-source-reset content 4.0.0 Remove all live sources from the player. Applies to HMP350 and HMP300.
llmnr-enabled network 4.7.0 Control whether Windows compatible name resolution (LLMNR) is enabled on the player.
maximum-latency rendering 2.2.1 4.7.2 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-enabled-secure network, interactivity 4.3.0 Enable or disable the secure access (CoAP REST API over TLS-PSK) to the Shared Variables Network API. Doesn't apply to HMP300 and DiVA.
network-api-port network 2.2.1 Set the port used by the Shared Variables Network API to listen to incoming connections. Doesn't apply to HMP300 and DiVA.
network-api-server network, interactivity 4.3.0 Set the default Shared Variables Network API server address, which is used whenever a Shared Variable does not specify a server address using the @ notation. Doesn't apply to HMP300 and DiVA.
network-api-psk network, interactivity 4.3.0 Set a pre-shared key to be used by the Shared Variable Network API server to encrypt communications. 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 peripherals 2.2.1 Disable the usage of FSM protocol file. Doesn't apply to DiVA.
protocol-file peripherals 2.2.1 3.0.0 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-file-reset peripherals 3.1.0 Remove all FSM files that are present on the device. Doesn't apply to DiVA.
protocol-simple peripherals 4.0.1 Configure one or more (simple) commands for screen control, to be sent over the serial port. Doesn't apply to DiVA.
protocol-system peripherals 2.2.1 3.0.0 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 4.0.0 Set a static Pull Mode configuration. Last modified in 4.0.0 firmware. Doesn't apply to DiVA.
pullmode-http-capture-log logs 4.4.0 Enable capturing the HTTP traffic for Pull Mode. Applies to HMP350 and HMP400/W.
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.
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.
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.
scheduled-download-reset content 4.0.0 Remove all scheduled downloads from 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 4.2.2 Add an HTTP server certificate to the device. Last modified in 4.2.2 firmware.
server-certificates-reset security 4.2.0 Remove all server certificates that are present on the device.
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.
streaming network 4.7.0 Enable/disable the streaming of the player’s video output. Applies to HMP400/W.
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 4.3.0 Create a new user, update an existing user or remove an existing user. Last modified in 4.0.0 firmware.
user-reset security 4.0.0 Remove all configured users (except the admin user).
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.
video-output-selector display 4.5.0 4.8.0 Select the video output of the player. Applies to HMP400/W.
volume display 4.7.2 Set the output volume of the audio device.
webstorage-token security 4.3.0 Set or clear the Web Storage token. Applies to HMP350.
wifi-ap-add network 4.5.1 Add a new entry to the Wi-Fi access point list. Applies to HMP400W.
wifi-ap-reset network 4.5.1 Clear the Wi-Fi access point list. Applies to HMP400W.
wifi-dhcp network 2.2.1 Configure the player to use Wi-Fi for its network connection with a DHCP assigned address for its IPv4 configuration. Applies to HMP400W.
wifi-static network 2.2.1 Configure the player to use Wi-Fi for its network connection with a fixed IPv4 address. Applies to HMP400W.
wifi-v6-none network 4.2.3 Configure the player to not add any IPv6 address to the Wi-Fi interface, apart from the SLAAC (Stateless Address Auto-configuration) assigned addresses. Applies to HMP400W.
wifi-v6-static network 4.2.3 Configure the player to add a fixed IPv6 address to the Wi-Fi interface. Applies to HMP400W.
wired-auth-add network 4.5.1 Set the 802.1x authentication parameters for Ethernet. Applies to HMP400/W.
wired-auth-reset network 4.5.1 Clear the 802.1x authentication parameters on Ethernet. Applies to HMP400/W.

Examples

Add admin user

The configuration string below adds a new user with administrator rights on the player. 

<?xml version="1.0"?> 
<configuration version="2.1"> 
<user>
    <username>admin2</username>
    <password>Your_38_characters_STRONG_PASSWORD! ;)</password>
    <admin>yes</admin>
</user>
</configuration>

Feel free to change the username and the password (it must be at least 8 characters long and must contain at least 1 uppercase letter, 1 lowercase letter, and 1 punctuation mark).

Set display settings

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>

Set Scheduled Download

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>

API deprecation

The technical documentation at the top of the page applies to HMP400, HMP400W, HMP350, HMP300, and DiVA players. For HMP200 and other legacy players, see this file.

See also

Retrieved from "https://support.spinetix.com/w/index.php?title=Configuration_API&oldid=19378"
This page was last modified on 20 August 2024, at 11:41.