RCI request

Remote Command Interface (RCI) is a method for remote clients to control, configure, and gather statistics from Digi Connect devices. RCI is a stateless, request/response protocol. RCI uses XML and HTTP to exchange data between clients and Digi devices.

RCI over HTTP

RCI requests are sent to the device using an URI of UE/rci. For example, if the Digi Device’s IP address is 192.168.1.1, then RCI requests are sent to http://192.168.1.1/UE/rci.

RCI requests are sent as an HTTP POST with the XML request of the form specified in this document. Note, due to space limitations on the device, the largest request that can be processed is 32KB. If a request is larger than this, it must be split into multiple RCI requests. RCI replies from the device are not subject to this limit.

Security is handled in the usual HTTP mechanism. The username and password must be passed to the device in the header of each HTTP request.

RCI over serial

RCI requests can also be sent over the serial port. This is useful in scenarios where a master processor is connected to the Digi Device through a serial port. This allows the master processor to configure the Digi Device as part of its configuration process, so that a separate manual configuration step for the Digi Device is eliminated. You must enable 'RCI over Serial' in either the Web Interface or the Command Line Interface before the Digi Device will accept RCI requests and return replies. The RCI over Serial option is available only on the primary port. RCI over Serial uses the DSR (Data Set Ready) serial signal. Verify that the serial port is not configured for autoconnect, modem emulation, or any other application which is dependent on DSR state changes.

Note When the Digi Device sees its DSR raised, it will set the serial port settings to 9600 baud, 8 data bits, no parity, and 1 stop bit. When DSR is lowered, the Digi Device will restore the previous serial settings.

Configure using the Command Line Interface (CLI)

Access the CLI using telnet or rlogin and the module's IP address. Ex:

telnet 192.168.1.2 -or-
rlogin 192.168.1.2

At the command prompt type:

 #> set rciserial state=on

Configure using the web user interface

Access the web interface by entering the module’s IP address in a browser’s URL window.
Choose Serial Ports from the Configuration menu.
If the device has more than one port, select Port 1.
If a port profile has not been selected, select Custom and click Apply.
Select Advanced Serial Settings.
Select Enable RCI over Serial (DSR) and click Apply.

RCI request/reply

An RCI XML document is identified by the XML elements rci_request and rci_reply. An RCI request specifies the XML element “rci_request” optionally with a version number. The version should match the version of RCI the client expects. The current RCI version is 1.1. If a version is not specified, the RCI version of the device is used to form the reply. Not specifying a version can cause problems when communicating with devices at different RCI versions, if the client code is not written in a version independent way. Therefore, it is highly recommended to always supply the version of RCI in requests, unless the client code has been designed to be version independent. Example of a request element:

<rci_request version="1.1">

The device will respond to requests with the element "rci_reply" along with the version number as an attribute. Example reply:

<rci_reply version="1.1">

rci_reply errors

Errors that occur at the request level will result in an error element as a sub-element of the <rci_reply>. Errors and warnings are explained below <rci_reply> errors: Error ID Description

Request not valid XML
Request not recognized
Unknown command

Command

The command section of the protocol indicates the action requested (or action performed in replies).

Commands are specified as sub-elements to <rci_request> and <rci_reply>.

This example requests all configuration settings:

    <rci_request version="1.1"> <!—Identifies the protocol and whether this is a request or a response --
        <query_setting/> <!— request config of device -->
    </rci_request>

This example requests the configuration information for just boot settings and serial settings.

    <rci_request version="1.1">
        <query_setting>
            <boot/>
            <serial/>
        </query_setting>
   </rci_request>

Supported commands

COMMAND	REQUEST DESCRIPTION	RESPONSE DESCRIPTION
query_setting	Request for device settings. May contain setting group elements to subset query (only setting group subset supported. Subsetting below this level not supported).	Returns requested config settings. Requests specifying no settings groups (eg. <query_setting/>) return all settings.
set_setting	Set settings specified in setting element. Settings data required.	Empty setting groups in reply indicate success. Errors returned as specified below.
query_state	Request current device state such as statistics and status. Sub-element may be supplied to subset results.	Returns requested state. Requests specifying no groups (eg. <query_state/> return all state.
set_factory_default	Sets device settings to factory defaults. Same semantics as set_setting.	Same semantics as set_setting.
reboot	Reboots device immediately.	None
do_command	See RCI do command	See RCI do command

Errors and warnings

Response documents may contain an element as a child of the command or data element that indicates the result of the request. More than one error or warnings may be present. Error and Warning elements:

error

An error occurred.

Attribute id: A numeric id specified by the parent element (the command or the data element). An error element id="0" is equivalent to no error.

Children Elements
name	desc
desc	Optional - Text description of the error.
hint	Optional - Used to indicate to the client the source of the error. This will typically be set to the field name that the error.

warning

Command executed, but a warning was issued.

Example:

    <serial_setting>
       <error id="3">
           <hint>baud</hint>
           <desc>Value out of valid range.</desc>
       </error>
        </serial_setting>

Errors are required to have an id. <hint> and <desc> are optional and more than one are allowed.

Notes

RCI XML must be well-formed XML

The device parses incoming RCI requests in a sequential manner. Each XML element is parsed and acted upon as it arrives. This is not ideal behavior, but is necessary because of the inherent resource limitations of a device. Ideally, the entire XML request would be read into memory, validated, parsed and acted upon only after validation.

XML structure errors may be found after actions have been taken. For instance:

    <rci_request version=”1.0”>
        <set_factory_default/>
    </rci_requestBADENDTAG>

This request will result in an XML parse error, but since the parse error occurs after the set_factory_defaults, the device will be set to factory defaults. Therefore, it is highly recommended that RCI requests be validated with an XML parser before being sent to the device. Using any standard parsers, such as the XML parsing in the Java SDK, to form RCI requests accomplishes this.

XML structure characters must not be sent as character data

Care must be taken to avoid accidental badly formed XML in RCI requests because of including XML structure characters, such as "<", as user entered data. Any field that accepts character data must be checked to ensure that "<" and ">" are not present (fields such as the email body of an alarm are common places this can happen). It is recommended that all instances of "<" and ">" in character data be converted to "&lt" and "&gt", which is the standard XML representation(entities) of these characters.

To use RCI to Query DIA device/channel Information

Reading device/channel information by direct HTTP to a DIA device requires a different do_command set. See Simple RCI by HTTP for working code examples.

References

https://www.digi.com/search/results?q=900005www.digi.com/search/results?q=9000056969