XML Interface¶

The xPico 600 embedded gateway provides an XML interface to configure the gateway using XML configuration records (XCRs). XML configuration records are easy to edit with a standard text editor or an XML editor.

For a brief overview of XML, see XML Configuration Language. It provides rules on basic XML syntax, a guide to the specific XML tags used, and a guide to using XML configuration records.

For additional guidelines for importing and exporting XML configuration, see Best Practices for XML Configuration.

You can use either of the following methods to import and export XML configuration:

Using the CLI to configure XML over serial port
Using Web APIs to configure XML over the network

You can also export XML status record (XSR) groups and items. To do this using the CLI, see Exporting XML Status (XSR) over Serial Port. To do this using the Web APIs, see Configuring XML over the Network.

Configuring XML over Serial Port¶

The serial port can be used to import and export XML configuration.

To ensure optimal performance when configuring and managing the device using XML, you must enable serial port flow control. This may be hardware or software flow control, which can be set up by means of the CLI if necessary. We recommend the use of hardware flow control to ensure the best throughput.

The CLI can be accessed via the methods previously described, as well as the following methods:

From the Modem Emulation serial application by entering the "ATD 0" command
From the TruPort Socket (Mux) application by entering the "D" command

To configure flow control options on the CLI:

Navigate to the config level to display the config> prompt.
Navigate to the Line 1 level to display the config Line 1> prompt.
Type Flow Control Hardware or Flow Control Software and press Enter on the keyboard.

Note

Software flow control experiences overrun above 460800 baud.

Example CLI:

> config
config> Line 1
config Line 1> Flow Control Hardware
Changed Line 1 Flow Control to "Hardware".
WARNING: Change will not persist after reboot unless you "write".

Exporting XML Configuration (CLI)¶

You can export an entire XCR or a partial XCR directly to the serial line CLI.

Connect the gateway to the PC and access the CLI.
Navigate to the xml level to display the xml> prompt.
Issue the xcr dump command to export the entire XML configuration or xcr dump [group-list] to export a portion of the XML configuration.
Copy and paste the configuration text into a basic text editor or XML editor.
Remove all the spaces in the script within the text editor. The basic text is the exported XML configuration and is now available for copy-paste into any xPico 600 gateway.

Tip

To export the entire XCR, issue the xcr dump command.
To export a portion of the XML configuration, issue the xcr dump [group-list] command.
To specify an instance of a group, issue the xcr dump [group:instance] command.
To export multiple groups, separate the groups with a semicolon. For example: xcr dump clock;interface

Example XML export output:

xml> xcr dump clock
<?xml version="1.0" standalone="yes"?>
<!-- Automatically generated XML -->
<!DOCTYPE configrecord [
   <!ELEMENT configrecord (configgroup+)>
   <!ELEMENT configgroup (configitem+)>
   <!ELEMENT configitem (value+)>
   <!ELEMENT value (#PCDATA)>
   <!ATTLIST configrecord version CDATA #IMPLIED>
   <!ATTLIST configgroup name CDATA #IMPLIED>
   <!ATTLIST configgroup instance CDATA #IMPLIED>
   <!ATTLIST configitem name CDATA #IMPLIED>
   <!ATTLIST configitem instance CDATA #IMPLIED>
   <!ATTLIST value name CDATA #IMPLIED>
]>
<configrecord version = "0.1.0.1">
   <configgroup name = "Clock">
      <configitem name = "Source">
         <value>NTP</value>
      </configitem>
      <configitem name = "UTC Offset">
         <value>0 minutes</value>
      </configitem>
   </configgroup>
</configrecord>

Importing XML Configuration¶

You can import an entire XCR or a partial XCR directly to the serial line CLI.

Refer to Best Practices for XML Configuration for guidelines about importing the XML configuration.

Modify the XML configuration in a basic text editor or XML editor.
Copy and paste the XML configuration text at the CLI prompt in the terminal emulator connected to the gateway. The gateway immediately processes the configuration record, changing any settings specified. This can be done at any CLI level, including root.

Example XML configuration import:

<?xml version="1.0" standalone="yes"?>
<!-- Automatically generated XML -->
<!DOCTYPE configrecord [
   <!ELEMENT configrecord (configgroup+)>
   <!ELEMENT configgroup (configitem+)>
   <!ELEMENT configitem (value+)>
   <!ELEMENT value (#PCDATA)>
   <!ATTLIST configrecord version CDATA #IMPLIED>
   <!ATTLIST configgroup name CDATA #IMPLIED>
   <!ATTLIST configgroup instance CDATA #IMPLIED>
   <!ATTLIST configitem name CDATA #IMPLIED>
   <!ATTLIST configitem instance CDATA #IMPLIED>
   <!ATTLIST value name CDATA #IMPLIED>
]>
<configrecord version = "0.1.0.1">
   <configgroup name = "Clock">
      <configitem name = "Source">
         <value>Manual</value>
      </configitem>
      <configitem name = "UTC Offset">
         <value>0 minutes</value>
      </configitem>
   </configgroup>
</configrecord>

Exporting XML Status (XSR) over Serial Port¶

The XML status record shows the status of the device. You can export the XML status using the serial port or the Web APIs. To export using the Web APIs, see Configuring XML over the Network.

As with the XML configuration, you can export an entire XSR or a partial XSR directly to the serial line CLI.

Connect the gateway to the PC and access the CLI.
Navigate to the xml level to display the xml> prompt.
Issue the xsr dump command to export the entire XML configuration or xsr dump [group-list] to export a portion of the XML configuration.

Tip

To specify an instance of a group, issue the xsr dump [group:instance] command.
To export multiple groups, separate the groups with a semicolon. For example: xsr dump clock;interface

Example output:

xml>xsr dump clock
<?xml version="1.0" standalone="yes"?>
<!-- Automatically generated XML -->
<!DOCTYPE statusrecord [
   <!ELEMENT statusrecord (statusgroup+)>
   <!ELEMENT statusgroup (statusitem+,statusgroup*)>
   <!ELEMENT statusitem (value+)>
   <!ELEMENT value (#PCDATA)>
   <!ATTLIST statusrecord version CDATA #IMPLIED>
   <!ATTLIST statusgroup name CDATA #IMPLIED>
   <!ATTLIST statusgroup instance CDATA #IMPLIED>
   <!ATTLIST statusitem name CDATA #IMPLIED>
   <!ATTLIST statusitem instance CDATA #IMPLIED>
   <!ATTLIST value name CDATA #IMPLIED>
]>
<statusrecord version = "0.1.0.1">
   <statusgroup name = "Clock">
      <statusitem name = "Current Time">
         <value>2018-01-17 22:42:54</value>
      </statusitem>
   </statusgroup>
</statusrecord>

Configuring XML over the Network¶

You can use the Web APIs to import and export XML configuration as well as export XML status.

Exporting XML Configuration

You can export the entire XML configuration or only a portion of the XCR. To export a portion, specify each group using the optionalGroupList parameter, with groups separated by a semicolon.

To export the entire XML configuration:

curl --anyauth -k -u admin:PASSWORD http://<ip-address>/export/config -X POST

To export a portion of the XML configuration:

curl --anyauth -k -u admin:PASSWORD http://<ip-address>/export/config -X POST -d "optionalGroupList=Interface:wlan0"

For additional cURL and Javascript examples, see Export Configuration Group in the Web API Reference.

Importing XML Configuration

The configuration can be imported from a local file in the file system of the gateway or with the configuration as part of the command.

An example to import the clock source using the configuration in the command would look as follows:

cURL example (configuration as part of command):

curl --anyauth -k -u admin:PASSWORD http://<ip-address>/import/config -X POST --form-string 'configrecord=<?xml version="1.0" standalone="yes"?>
<!-- Automatically generated XML -->
<!DOCTYPE configrecord [
   <!ELEMENT configrecord (configgroup+)>
   <!ELEMENT configgroup (configitem+)>
   <!ELEMENT configitem (value+)>
   <!ELEMENT value (#PCDATA)>
   <!ATTLIST configrecord version CDATA #IMPLIED>
   <!ATTLIST configgroup name CDATA #IMPLIED>
   <!ATTLIST configgroup instance CDATA #IMPLIED>
   <!ATTLIST configitem name CDATA #IMPLIED>
   <!ATTLIST configitem instance CDATA #IMPLIED>
   <!ATTLIST value name CDATA #IMPLIED>
]>
<configrecord version = "0.1.0.1">
   <configgroup name = "Clock">
      <configitem name = "Source">
         <value>NTP</value>
      </configitem>
   </configgroup>
</configrecord>'

For examples using a local file or HTTP, see Import Configuration Group in the Web API Reference.

Exporting XML Status Records (XSR)

You can export the entire XML status record or only a portion of it. To export a portion, specify each group using the optionalGroupList parameter, with groups separated by a semicolon.

To export the XSR:

curl --anyauth -k -u admin:PASSWORD http://<ip-address>/export/status -X POST

To export a portion of the XSR:

curl --anyauth -k -u admin:PASSWORD http://<ip-address>/export/status -X POST -d "optionalGroupList=Device;Clock"

For additional cURL and Javascript examples, see Export Status Group in the Web API Reference.

Best Practices for XML Configuration¶

You can import or export an entire XCR, or just a portion of it, by specifying the group name and/or group instances. The following guidelines apply to importing an XML configuration using the CLI or Web APIs.

Missing Values¶

When importing an XCR, you do not need to supply all of the configuration items. However, depending on your import control, there are two possible behaviors for the missing values:

Missing Values are left unchanged:
- Default if the XML Import Control group is absent from the XCR
- Explicit if the XML Import Control group contains the item Missing Values "Unchanged"
Missing Values are set to Default for that value:
- Default if the XML Import Control group is present but the item Missing Values is absent from the XCR
- Explicit if the XML Import Control group contains the item Missing Values "Set to Default"

Passwords in the XML¶

When you export an XCR that contains secret fields, such as passwords and keys, the secret field values are replaced with the <Configured> placeholder. You will need to manually replace the placeholder with the actual secret value before you import the configuration. This applies to both the CLI and Web API methods.

Special Characters to be Replaced¶

Special characters that appear in the XCR as values must be replaced. For example, if your password contains any of the following special characters, you must replace them with the HTML character reference.

Special Character	Replacement
&	`&`
<	`<`
>	`>`
‘	`'`
“	`"`

Removing Non-printable Characters from XCR¶

Some text editors may add extraneous non-printable characters to the XML configuration file. When you try to import the XML configuration, these extraneous characters will not be accepted by the gateway. To avoid errors due to added meta characters, we suggest that you use a basic text editor such as Notepad++ to edit the XML configuration files.

XML Configuration Language¶

The gateway provides an Extensible Markup Language (XML) interface that you can use to configure gateway's embedded device servers. Every configuration setting, excluding XML import and export, that can be issued from the Web Manager and CLI can be specified using XML.

The gateway can import and export configuration settings as an XML document known as an XML Configuration Record (XCR). An XCR can be imported or exported via the CLI. An XCR can contain many configuration settings or just a few. For example, it might change all of the configurable parameters for a gateway, or it may only change the baud rate for a single serial line. Using XCRs is a straightforward and flexible way to manage the configuration of multiple gateways.

Imported and exported XCRs begin with the following text:

<?xml version="1.0" standalone="yes"?>
<!DOCTYPE configrecord [
   <!ELEMENT configrecord (configgroup+)>
   <!ELEMENT configgroup (configitem+)>
   <!ELEMENT configitem (value+)>
   <!ELEMENT value (#PCDATA)>
   <!ATTLIST configrecord version CDATA #IMPLIED>
   <!ATTLIST configgroup name CDATA #IMPLIED>
   <!ATTLIST configgroup instance CDATA #IMPLIED>
   <!ATTLIST configitem name CDATA #IMPLIED>
   <!ATTLIST configitem instance CDATA #IMPLIED>
   <!ATTLIST value name CDATA #IMPLIED>
]>
<configrecord version="0.1.0.1">

All configgroups are positioned in the middle. Then the XML must end with the following text:

</configrecord>

XML Syntax¶

A <configrecord> element must have one or more <configgroup> elements and can have a version attribute.
Each <configgroup> element must have one or more <configitem> elements, must have a name attribute and may have instance attributes.
A <configitem> element must have one or more <value> elements, must have a name attribute, and may have an instance attribute.
A <value> element contains data and may have a name attribute.
The name attribute identifies a group, item, or value. It is always a quoted string.
The instance attribute identifies the specific instance when more than one instance is possible. The instance attribute is always a quoted string.
An empty or missing <value> element in each present <configgroup> clears the setting to its default.

Element Start and End Tags¶

An element consists of a start tag and an end tag that surrounds text and other elements. The start and end tags consist of a name surrounded by angle brackets, with a forward slash also preceding the name in the end tag. For example: <configrecord> _some elements_ </configrecord>. The element can also contain other "child" elements.

Element Attributes¶

The XML element attributes are name-value pairs included in the start tag after the element name. The values must be quoted, using single or double quotes. Each attribute name should appear only once in an element.

XML Example:

<configgroup name = "Clock">
  <configitem name = "Source">
    <value>Manual</value>
  </configitem>
</configgroup>

The gateway uses the attributes in the following section to label the group configuration settings.

Record, Group, Item, and Value Tags¶

A configgroup is a logical grouping of configuration parameters and must contain one or more configitem elements. It must have a name attribute and may have an instance attribute.

A configitem is a specific grouping of configuration parameters relevant to its parent group. An item takes the name attribute and must contain one or more value elements.

A value may specify the value of a configuration parameter. It may contain the name attribute.

A name attribute identifies the group, item, or value. It is always quoted (as are all XML attributes).

An instance attribute identifies which of several instances is being addressed. It is always quoted.

The following examples demonstrate the use of the record, group, item, and value XML elements in an XML configuration record.

Example of the use of multiple groups and multiple items:

<configrecord version = "0.1.0.1">
   <configgroup name = "Clock">
      <configitem name = "Source">
         <value>Manual</value>
      </configitem>
   </configgroup>
   <configgroup name = "Interface" instance = "ap0">
         <configitem name = "IP Address">
            <value>192.168.0.1/24</value>
         </configitem>
      </configgroup>

Example of the use of multiple named values:

<configrecord version = "0.1.0.1">
   <configgroup name = "CPM">
      <configitem name = "Role" instance = "AP Trigger">
         <value name = "CP">&lt;No CP Selected&gt;</value>
         <value name = "State">Disabled</value>
         <value name = "Assert">High</value>
         <value name = "Mode">Push-Pull</value>
      </configitem>
   </configgroup>
</configrecord>