HMP Configuration API

From SpinetiX Support Wiki

Jump to: navigation, search

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

Introduction

The HMP Configuration API defines the XML format and all the configuration commands that can be used to modify different settings on the HMP devices.

The HMP Configuration API is available since 2.2.1 firmware release, when the configuration backup & restore feature was introduced in HMP Control Center, and extended in 2.2.3 release to be used through RPC calls. Further changes and improvements of the HMP configuration API were regularly done in subsequent firmware releases.

There are two methods to send configuration commands to an HMP for execution:

To get started, you might want to generate a configuration backup from HMP Control Center and check the config.xml file included within, or send a get_config() RPC command to the HMP and check the result.

XML configuration string

The HMP Configuration API uses an XML-based format, where one or more configuration commands are encapsulated within a <configuration> element.

The XML configuration string must have the following structure:

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

The <configuration> element has a "version" attribute whose value depends on the firmware:

  • "1.0" for firmware versions below 3.0.0.
  • "1.1" for firmware versions 3.0.x and 3.1.x (the syntax of two existing configuration commands changed).
  • "1.2" for firmware versions 3.2.x (two commands added).
  • "2.0" for firmware versions 4.x (for HMP350 and HMP300).
Notes
  • The XML configuration string can reflect a full configuration of the HMP device (as it is the case for when the configuration backup is generated from HMP Control Center), or it can update only a limited number of settings (in this case, the settings not found in the configuration string 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).
  • The configuration commands are executed in the order provided (except for the <reboot/> command) and this might influence the end result. For instance the <ethernet-dhcp/> command will set the player to DHCP, whereas the <ethernet-static> command will set it to use a fixed IP address. If both commands are present in the XML configuration string, the last one will be taken into consideration.
Example

The XML configuration string below sets the aspect ratio of the screen to 16:9 and its orientation to horizontal, and forces a reboot to apply the changes. No other parameters are modified.

<?xml version="1.0"?>
<configuration version="1.2">
    <screeen-aspect-ratio>16:9</screeen-aspect-ratio>
    <display-orientation>horizontal</display-orientation>
    <reboot/>
</configuration>

Configuration commands

A configuration command is represented within the XML configuration string through an XML element, direct descendant of the <configuration> element.

  • In case the configuration command requires one parameter, it is usually provided within the text content of the element.
  • If it requires more parameters, these are usually provided as inner XML elements.

Note Note: Further details about each configuration command can be found within the technical documentation.

Examples

To configure the HMP to use DHCP, a simple XML element is used:

<ethernet-dhcp/>

To change the time zone setting, the time zone name is specified within the text content of the element:

<timezone>Europe/Zurich</timezone>

To set the HMP device to use a fixed IP address, several parameters are needed, each being provided as a separate XML element under the main command:

<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>
This page was last modified on 29 August 2017, at 20:49.