How can I configure embedded Evolution device servers with XML?

---

Extensible Markup Language (XML) is a fundamental building block of the Internet. XML is a set of rules for encoding documents and configuration electronically. Its simplicity and popularity make it an ideal choice as a format for configuration data. All Lantronix Evolution (EVOS) based Device Servers (Such as the XPort Pro, MatchPort b/g Pro and the MatchPort AR) support an XML-based configuration interface that make device configuration or status retrieval simple and fast. This XML interface allows the EVOS device to be configured via the CLI (serial or network channels), a Web browser, FTP, or the device server's internal file system. This article explores using the XML interface to configure an EVOS device via the CLI through the serial or network interface. This will also be of interest to Engineers looking to read and write configuration data at run time by an embedded host processor.

The Basics

EVOS supports the use of two different types of XML records. To read or write (import / export) configuration data there are XML Configuration Records (XCRs). To query the device (read only) for status information there are XML Status Records (XSRs). There is a slight difference between the XML schema on the XCRs and the XSRs. However, the major difference between the two is that an XSR can only be exported from a device.

The format of XCRs and XSRs are made up as a record. In each record, there is a group name and for each group, there are item names. The item names pertain to the individual configuration fields that you want to change. For example, the "Device" group consists of the following item names:

The XML interface offers a lot of flexibility for device configuration. An XCR record can contain all of the item names or just a few. For the "Device" group it might contain all 3 of the item names (configurable parameters) or it may only contain the "short name" item to change. A record can also contain more than one group. An example will follow under "write an XML record" that will show the power of this. One other point worth mentioning, some groups (not all of them) can have more than one Instance. This is useful for configuration groups like "serial". If the device contains more than 1 serial port, then the Instance number selects the serial port channel that will be affected.

The appropriate Command Reference document will list all of the XCR and XSR groups that are defined for each device. However, they are also easily obtained through the CLI at the enable level by issuing either of the following commands:

(enable)# xcr list
(enable)# xsr list

For serial to network modules (such as the MatchPort AR, Matchport BG Pro or the XPort Pro), an XML configuration record can be imported or exported directly through the serial interface using a HyperTerminal session or through a custom program written in C/C++. For Ethernet to WiFi applications (using the MatchPort BG Pro), an XML configuration record can be imported or exported directly through the Ethernet interface using a Telnet session or through a custom program written in C/C++. A word of caution - there are slight differences in the XML commands between EVOS based products. However, for any one Lantronix module, the XML record format is the same between all interfaces. So, an XML record that is used through the serial interface would work identically if it were sent over the network interface.

How to Read an XML record

To export or read configuration or status data through the CLI, an XCR or XSR records can be used depending on what data is needed. However, these records must be entered at the Enable level of the CLI. This can be easily accomplished by entering Enable at the '>' prompt

> Enable <crlf>

This is different from importing or writing XML configuration records. Writing records can be done at any level including the root. If the enable level is password protected, special tags can be added to the XML for providing root and enable level passwords to allow access.
To read the firmware version of a module, use the "firmware" group. The firmware group only has one item name "version". Issue the following command:

(enable)# xcr dump firmware <crlf>

"xcr dump" is the command and "firmware" is the group name. The "firmware" group will return the current version number of the installed FW. Once you issue the "xcr dump firmware" command, the EVOS device will return the following information:

< ! xml details omitted for clarity >
<configgroup name = "firmware">
<configitem name = "version">
<value>1.3.0.0R9</value>
</configitem>
</configgroup>
</configrecord>

In this example, it is easily seen that the FW version is 1.3.0.0R9.

To read device information using the "device" group, issue this command:

(enable)# xcr dump device <crlf>

The "device" group will return the short name, long name and the serial number of the device. Once you issue the "xcr dump device" command, the EVOS device will return the following information:

< ! xml details omitted for clarity >
<configgroup name = "device">
<configitem name = "short name">
<value>matchport_bg_pro</value>
</configitem>
<configitem name = "long name">
<value>Lantronix MatchPort b/g Pro</value>
</configitem>
<configitem name = "serial number">
<value>77082417J6N1JR</value>
</configitem>
</configgroup>
</configrecord>

From the configgroup name line, the group name from this data is clearly the device group. This data can easily be parsed for the short and long names as well as the serial number.

The XCR dump command offers a lot of flexibility. Consider the following examples:

(enable)# xcr dump line <crlf>

This command will dump the XCR records for both instances of the "line" group. In this case, it is line 1 and line 2.

(enable)# xcr dump line:1 <crlf>

This command will dump the XCR records for the single instance of the "line" 1 group only. Here is the last example:

(enable)# xcr dump "line:1; syslog; device" <crlf>

This command will dump the XCR records for the single instance of the "line" 1 group and the "syslog group. Multiple groups can be combined on one command line. Please note that the groups must be enclosed in parenthesis (").

Reboot and getting the configuration to take effect

On EVOS, all configuration changes made using an XCR record will take effect after the device has been rebooted. Fortunately, there is a very handy way to handle this. For most Lantronix devices, there is a group called "XML import control". There are several item fields under this group but the most interesting for this discussion is the item name - "reboot". To force a reboot, simply send this record with the reboot item enabled through the proper XML interface..

<?xml version="1.0" standalone="yes"?>
<configrecord>
<configgroup name="xml import control">
<configitem name="reboot">
<value>enable</value>
</configitem>
</configgroup>
</configrecord>

This record will cause the device to reboot. This setting will also force a reboot every time a subsequent XCR record is written to the device. If multiple records are written, it is good practice to disable the reboot field on all records until the last one.

How to Write an XML record

To import or write configuration data through the CLI can be done on any level, including the root. In other words, you do not have to enter the Enable level. Writing an XCR configuration record can be started by sending a valid XCR record directly to the CLI prompt. There is no command required. Simply write or send the XCR record to the CLI. EVOS will immediately process the configuration record, changing any settings specified in the XCR. To change the short name on a module, the following XCR record will work.

<?xml version="1.0" standalone="yes"?>
<configrecord>
<configgroup name = "device">
<configitem name = "short name">
<value>M_bg_pro</value>
</configitem>
</configgroup>
<configgroup name="xml import control">
<configitem name="reboot">
<value>enable</value>
</configitem>
</configgroup>
</configrecord>

Notice that this record only contained one item name in the "device" group. Also notice that this record contained two groups - the "device" group and the "xml import control" group. It is a good practice to always include the "xml import control" group in every XCR record that is being written to the device. This allows the user to easily set and verify whether the module will be reboot.

For further information on the XML interface, please refer to the appropriate Lantronix documentation, available here ( http://www.lantronix.com/support/downloads/ )

---

[Originally Published On: 08/20/2010 05:04 PM]