RCI (Remote Command Interface) Specification - 90000569_G
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
RCI (Remote Command Interface)
Specification
90000569_GTable of Contents
1 Introduction ................................................................................................................................6
1.1 What is Remote Command Interface (RCI)? ................................................................................. 6
1.2 Terminology .................................................................................................................................. 7
1.3 Related documentation ................................................................................................................ 7
2 The RCI protocol ..........................................................................................................................8
2.1 RCI request and reply XML documents ......................................................................................... 8
2.2 Transport layer .............................................................................................................................. 8
2.3 RCI document structure ................................................................................................................ 9
2.3.1 and .................................................................................................. 9
2.4 RCI commands ............................................................................................................................ 10
2.4.1 Supported commands ............................................................................................................. 10
2.4.2 Compound commands ............................................................................................................ 10
2.4.3 Command rules ....................................................................................................................... 11
3 RCI command reference ............................................................................................................ 13
3.1 ..................................................................................................................... 13
3.1.1 Attributes ................................................................................................................................ 13
3.2 .......................................................................................................................... 14
3.2.1 Attributes ................................................................................................................................ 14
3.2.2 Example: .................................................................................................................................. 15
3.3 ............................................................................................................................... 16
3.3.1 Attributes ................................................................................................................................ 16
3.3.2 Required handling of read-only settings ................................................................................. 16
3.4 ............................................................................................................................. 17
3.4.1 Attributes ................................................................................................................................ 17
3.4.2 element .................................................................................................................... 17
3.5 .................................................................................................................................. 18
3.5.1 Attributes ................................................................................................................................ 18
3.6 ................................................................................................................. 19
3.6.1 Attributes ................................................................................................................................ 19
3.7 ...................................................................................................................................... 19
3.7.1 Attributes ................................................................................................................................ 19
3.8 .......................................................................................................................... 20
3.8.1 Attributes ................................................................................................................................ 20
3.9 ........................................................................................ 21
3.9.1 subcommand ................................................................................................................... 21
3.9.2 subcommand ......................................................................................................... 22
3.9.3 subcommand ......................................................................................................... 22
23.9.4 subcommand ................................................................................................................. 23
3.10 ................................................................................................ 24
3.10.1 RCI subcommands available and features on an XBee gateway......................................... 24
3.10.2 Support for XBee-related RCI subcommands ..................................................................... 24
3.10.3 subcommand .................................................................................................... 25
3.10.4 subcommand ................................................................................................ 28
3.10.5 subcommand....................................................................................................... 29
3.10.6 subcommand ........................................................................................... 30
3.10.7 subcommand .............................................................................................. 30
3.10.8 subcommand ....................................................................................... 31
3.10.9 subcommand .................................................................................. 33
3.10.10 subcommand ................................................................................................ 34
3.11 RCI errors and warnings .............................................................................................................. 35
3.11.1 Error and warning attributes .............................................................................................. 37
3.11.2 Error and warning tags ........................................................................................................ 37
4 RCI device implementers’ notes ................................................................................................. 38
5 Legacy RCI ................................................................................................................................. 39
5.1 RCI over HTTP .............................................................................................................................. 39
5.2 RCI over serial ............................................................................................................................. 40
5.2.1 Configure RCI over serial from the command-line interface (CLI) .......................................... 40
5.2.2 Configure RCI over serial from the web interface .................................................................. 40
6 RCI descriptors .......................................................................................................................... 41
6.1 Determining whether a device supports RCI descriptors ........................................................... 43
6.2 Information included in RCI descriptors ..................................................................................... 44
6.3 Assembling a set of descriptors into a single descriptor tree ..................................................... 46
6.4 Client requirements for parsing responses................................................................................. 49
6.5 Validating settings ....................................................................................................................... 49
7 RCI descriptor reference ............................................................................................................ 50
7.1 Format for descriptions .............................................................................................................. 50
7.2 Encrypted fields .......................................................................................................................... 50
7.3 ................................................................................................................................ 51
7.3.1 Purpose ................................................................................................................................... 51
7.3.2 Attributes ................................................................................................................................ 51
7.3.3 Allowed children ..................................................................................................................... 52
7.4 ........................................................................................................................................... 53
7.4.1 Purpose ................................................................................................................................... 53
7.4.2 Attributes ................................................................................................................................ 54
7.4.3 Allowed children ..................................................................................................................... 55
37.5 ........................................................................................................................................ 56
7.5.1 Purpose ................................................................................................................................... 56
7.5.2 Attributes ................................................................................................................................ 56
7.5.3 Allowed children ..................................................................................................................... 57
7.6 ................................................................................................................................... 58
7.6.1 Purpose ................................................................................................................................... 58
7.6.2 Attributes ................................................................................................................................ 58
7.6.3 Allowed children ..................................................................................................................... 60
7.7 ...................................................................................................................... 61
7.7.1 Purpose ................................................................................................................................... 61
7.7.2 Attributes ................................................................................................................................ 61
7.8 ............................................................................................................................. 62
7.8.1 Purpose ................................................................................................................................... 62
7.8.2 Example: Define errors common to all settings...................................................................... 62
7.8.3 Example: Use a grouped error ................................................................................................ 62
7.9 ......................................................................................................................... 63
7.9.1 Purpose ................................................................................................................................... 63
7.9.2 Attributes ................................................................................................................................ 63
7.9.3 Allowed children: .................................................................................................................... 63
7.10 .............................................................................................................................. 64
7.10.1 Purpose ............................................................................................................................... 64
7.10.2 Attributes ............................................................................................................................ 64
7.10.3 Allowed children: ................................................................................................................ 64
7.11 Descriptor types .......................................................................................................................... 65
7.11.1 “none” ................................................................................................................................. 65
7.11.2 “string” ................................................................................................................................ 65
7.11.3 “multiline_string” ................................................................................................................ 66
7.11.4 “password”.......................................................................................................................... 66
7.11.5 “int32” ................................................................................................................................. 66
7.11.6 “uint32” ............................................................................................................................... 67
7.11.7 “hex32” ............................................................................................................................... 67
7.11.8 “0x_hex32”.......................................................................................................................... 67
7.11.9 “float” .................................................................................................................................. 67
7.11.10 “enum” ................................................................................................................................ 67
7.11.11 “enum_multi” ..................................................................................................................... 68
7.11.12 “on_off” .............................................................................................................................. 68
7.11.13 “boolean” ............................................................................................................................ 68
7.11.14 “ipv4” .................................................................................................................................. 69
7.11.15 “fqdnv4” .............................................................................................................................. 69
47.11.16 “fqdnv6” .............................................................................................................................. 69
7.11.17 “multi” ................................................................................................................................. 69
7.11.18 “list” .................................................................................................................................... 70
7.11.19 “raw_data” .......................................................................................................................... 70
7.11.20 “xbee_ext_addr” ................................................................................................................. 71
7.11.21 “file_name” ......................................................................................................................... 71
7.11.22 “mac_addr” ......................................................................................................................... 71
7.11.23 “datetime” .......................................................................................................................... 72
7.12 conditional custom name=”xbee_type” ..................................................................................... 73
7.12.1 Calculations and terms used for testing the ”xbee_type” conditional ............................... 73
7.12.2 Steps for testing the “xbee_type” conditional.................................................................... 74
51 Introduction
1.1 What is Remote Command Interface (RCI)?
Remote Command Interface (RCI) is a mechanism designed to allow remote configuration, control, and
information exchange between an RCI client, typically a web services client acting via Device Cloud, and
an RCI target, typically a Digi device implementing the RCI specification. RCI consists of a transport
mechanism, such as the Device Cloud device protocol, EDP, and an XML-based request and reply
document specification. RCI allows a user to:
• Inspect and configure device settings
• Inspect and configure device state (such as inspecting network statistics or setting the level of a
GPIO pin)
• Reboot a device
• Configure XBee networks via Digi devices
• Device file system operations (list, get, put, delete)
• Send requests and retrieve replies from dynamically registered agents such as python programs
RCI requests are sent to devices via Device Cloud and are wrapped in a server request, called SCI. For
more information on SCI, see the Device Cloud Programming Guide.
For details about non- Device Cloud RCI information, see Legacy RCI on page 39.
Here is an example of an RCI request and reply that queries a device for its “system” configuration:
NewCos Device
Joe Thompson
Building 30-2
61.2 Terminology
The terminology used in this document follows XML definitions. See the XML Specification:
http://www.w3.org/TR/REC-xml/
Commonly used terms include:
• An XML element tag is dest in this example:
• An XML attribute is the index="23" in this example: , where index is the
name of the attribute, and "23" is the value of the attribute. Note the double-quote characters
are required.
• An RCI client is the originator of an RCI request. A client sends request to a device and a device
responds to a client.
1.3 Related documentation
• EDP Specification – Describes the Device Cloud device to server protocol
• Device Cloud User’s Guide—Digi part number 90001150
• Device Cloud Programming Guide—Digi part number 90002008
• XBee RF module Product Manuals
72 The RCI protocol
RCI is made up of two parts:
• XML documents containing requests and replies
• The Transport layer over which that content is exchanged between the server and device.
2.1 RCI request and reply XML documents
RCI exchanges data between clients and devices using XML documents. All RCI XML documents are well-
formed XML. To reduce the complexity of XML parsing on devices with limited capabilities, a limited set
of XML parsing requirements are enforced in an RCI-capable device:
• RCI requires only XML version 1.0.
• RCI uses ISO-8859-1 encoding. XML 1.0 requires XML parsers to be able to parse UTF-8. This
requirement is not enforced in XML parsers used for RCI in devices. If any RCI requests are sent
to Device Cloud in a different encoding than ISO-8859-1, Device Cloud transforms the request to
ISO-8859-1 (other transports behavior with non-ISO-8859-1 is not defined).
• Not all predefined entities need be supported. Only the following are required:
− &
− <
− >
− "
− '
• Entity declarations are not supported.
• Only simple StringData attribute types are required (see XML specification, section 3.3).
2.2 Transport layer
The Transport layer is a mechanism that handles communication between a server and a device. The
Transport layer specifies the initialization process, the sending and responding mechanism, the closing
mechanism, any error recovery mechanism needed, and security. The Transport layer for Device Cloud
is EDP. EDP is described in the EDP Specification.
For other RCI transports, see Legacy RCI on page 39.
82.3 RCI document structure
2.3.1 and
An RCI XML document is identified by the root XML elements or .
2.3.1.1
An RCI request specifies the XML element tag with an optional version number. The
version number should match the version of RCI the client expects.
The current RCI version number is 1.1. If a version number is not specified, the RCI version number of
the device is used to form the reply.
Here is an example request element:
A client forms an RCI request by building an XML document with as the root element. The
content of the request is a supported command with command specific content. Descriptions of the RCI
commands begin on page 10.
2.3.1.2
The device parses the RCI request, performs the requested action and forms a reply.
An RCI reply specifies the element tag along with the version number as an attribute. For
example:
An RCI reply is an XML document that is structured in the same way as the RCI request. If the request
was successful, the RCI reply contains no elements (see RCI errors and warnings on page 35).
The response document echoes the same structure as the request document, even when the request is
a command that does not return data. This is required so that a client can confirm the command was
executed successfully; it is also a means for the client to match up sub-command completion in a
compound request.
The following example demonstrates this request/reply symmetric relationship. The element is
data being added by the device in response to the request. This addition of shows the symmetry
is not exact, but rather at the container level, where the element is considered a container.
returned
92.4 RCI commands
The command section of the protocol indicates the action requested (or action performed in replies).
2.4.1 Supported commands
The following table summarizes the required commands in RCI. Command descriptions begin on page
13.
Devices may support additional commands. These custom commands will be reflected in a device’s RCI
descriptor.
Command Request description Reply description
Request device capabilities. RCI descriptor.
Request for device settings. Returns requested settings.
Set settings specified in setting Empty setting groups returned as
element. confirmation of set. Errors are
returned as specified in RCI errors
and warnings on page 35.
Set the device state. Same semantics as set_setting
Request current device state, such as Returns requested state.
statistics and status. Sub-element
may be supplied to subset results.
Sets device settings to factory Same semantics as set_setting.
defaults. Same semantics as
set_setting.
Reboots device immediately. Confirm reboot command.
Send a request to a subsystem Response from subsystem.
specified by the target element.
2.4.2 Compound commands
An RCI request can contain more than one command. The device replies with its command responses
concatenated together in one reply in the order in which they appear in the request. Here is an example
of a compound command:
102.4.3 Command rules
While the contents and structure of RCI commands vary, there are some rules that are common to all
commands.
2.4.3.1 Specifying commands
Commands are specified as a child element to and .
This example requests all configuration settings:
This example requests the configuration information for just system settings and serial settings. The
valid children of are determined by the command.
2.4.3.2 XML constraints
If an element has a child element, it must not also have character data as a child.
This structure is allowed:
character data ok
But this structure is not allowed:
illegal character data
character data ok
112.4.3.3 Data collections
When there is more than one set of data in a command, an attribute is used to uniquely identify the
item. There are two data structures that can be used:
• An array-like entry, using the attribute index.
• A hash map-like entry, using the attribute name.
2.4.3.3.1 Arrays
Arrays start at index 1 and continue to a stated maximum, as listed in the RCI descriptor. If there is a
natural mapping of an array, it should be documented in the RCI descriptor.
For example, if a device has two serial ports, then the index maps to a serial port. Serial ports are
selected as follows:
If a data element uses index as an attribute, as specified in its RCI descriptor, it can be assumed that the
data element is an array.
If a data element is an array type and the index attribute is not specified, index=”1” is implied on
operations that act on an instance, such as a .
2.4.3.3.2 Dictionaries
Dictionaries identify data instances by the attribute name. If there is a list of allowed names for a data
element, that list of names is specified in the RCI descriptor.
Dictionary data type example:
1.1.1.1
2.2.2.2
If a data element declares an attribute named “name”, the data element is a dictionary.
The name attribute is required for dictionary data. If a data element is a dictionary and a name attribute
is not specified on an instance operation, such as a , an error is returned.
123 RCI command reference
The following RCI commands are considered the standard set. Due to varying levels of implementation
as well as support that is dependent on device features, RCI descriptors must be used to determine the
exact set of supported commands.
•
•
•
•
•
•
•
• and its variants, and
3.1
is used to retrieve the RCI descriptor from the device. The RCI descriptor describes
all RCI commands supported on a device, as well as all children and contents of those commands. For
more information on the RCI descriptors, see page 41.
Support for the command is optional on a device, but is recommended. However,
RCI descriptors are required for a device managed by Device Cloud. If the
command is not supported on a device, a device maker must arrange to push the RCI descriptor up to
the server manually.
3.1.1 Attributes
None.
133.2
The command is used to request configuration parameters from a device.
Configuration is split into three separate sources:
• current: The current settings running in the device. The concept of “current” can vary device by
device and setting group by setting group. For instance, the current settings for a serial port are
naturally the initial settings of the port (the application opening the port can change the serial
port settings via IOCTLs once it has opened the port—this temporal change happens outside of
the configuration mechanism). Once the port is open, setting the “current” settings for serial
will just change the initial settings, not the actual running settings of the open port.
In cases where configuration current can differ from running values, it is recommended that the
current running values be exposed through a command group, since that is the
purpose of state in RCI.
• stored: The value that will be used on the next boot of the device.
• default: The value that will be present following a command.
Sending a without children returns all configuration of a device. Complete
configuration of a device needs to be returned in such a request. That is a full reply can
be used as a backup of the full configuration of a device.
The settings returned by are arranged in a set of groups (called setting groups) that
group logically associated configuration. The children of are setting groups.
The children of settings groups are field value pairs which make up the actual configuration. Values are
typed and are declared in the RCI descriptor. Available types are listed in the RCI Descriptors section on
page 41.
Field value pairs can optionally grouped together when appropriate. These groupings are called a list.
Alternatively, if an element X inside a setting group has child elements, then element X is a list. Lists
should not be nested more than one deep.
3.2.1 Attributes
The following attributes are optional but recommended in device implementations. If a device does not
support an attribute, it must behave as if the attribute is ignored and not return an error solely because
of an unknown attribute.
Supported attributes must be declared in the RCI descriptor. Devices can also add other attributes
specific to their device. All attributes must be declared in the RCI descriptor.
3.2.1.1 source
The source attribute lets a user request the settings from a particular source. Supported source values:
• “current”: The current running settings.
• “stored”: The configuration stored persistently. This is the configuration that will be used by the
device if it is rebooted.
• “defaults”: The default configuration of the device. This is the configuration that will be used if
is issued.
The default is “current.”
143.2.1.2 compare_to
The compare_to attribute works with the source attribute to return only the differences from the
compare_to settings and the settings source specified in source. For example, to return only the settings
that are different from defaults, issue this request:
Supported compare_to values include:
• “none”: No difference requested. Return all values as specified in source.
• “current”: The current running settings.
• “stored”: The configuration stored persistently. This is the configuration that will be used by the
device if it is rebooted.
• “defaults”: The default configuration of the device. This is the configuration that will be used if
is issued. The default value is compare_to=”none”
3.2.2 Example:
300
2
1200
1
1.2.3.4
tom, john
fred
bill
betty
153.3
The command is used to set device configuration. It follows the same structure as
.
3.3.1 Attributes
The following attributes are optional but recommended. If a device does not support an attribute, it
must behave as if the attribute is ignored. Supported attributes must be declared in the RCI descriptor.
Devices can also add other attributes specific to their device. All attributes must be declared in the RCI
descriptor.
3.3.1.1 action
Specifies when the should take place. Values include:
• “immediate”: The set is applied to the current running settings. This is equivalent to the
source=”current” in .
• “deferred”: The set is applied to NVRAM settings but not to current settings. This is equivalent
to source=”stored” in .
3.3.1.2 encrypt
Supported values:
• “1”: Use encrypt type “1”. Specifying the attribute encrypt=”1” instructs the device to return
sensitive information in encrypted form. The device determines which fields are determined
sensitive but in general sensitive fields include passwords and keys. Any field that is returned
encrypted is marked with an attribute encrypt=”1” in the reply. The encrypt attribute is also
declared in the descriptor for any field that may be returned this way. The actual encryption
method is not specified. The caller treats the value as opaque. The only use of an encrypted
value is as a backup of configuration that will later be set to the device.
• “none”: Do not encrypt fields. If encrypt=”none” is specified, it is recommended that sensitive
fields are not returned at all.
The default is encrypt=”none”.
3.3.2 Required handling of read-only settings
A warning (not an error) must be generated if a setting marked access=”read_only” (see page 52)is sent
as the contents of the command. This allows an RCI client to use a full result of a
in a command.
163.4
The command requests and returns information about the current state of the device.
Device state includes: statistics, device info, and transient events, such as GPS coordinates. The format
of the groups returned by is the same as for .
3.4.1 Attributes
None.
3.4.2 element
The element of the command is used to return information about
the XBee RF module installed in the gateway. For all other XBee nodes in the network, see
on page 24.
3.4.2.1 Example request and reply
01:23:45:67:89:ab:cd:ef!
0x1234
value
...
...
173.4.2.2 gateway_addr
The 64-bit extended device address of the XBee RF module on a gateway.
3.4.2.3 caps
A bitmap of gateway capabilities. See also “Calculations and terms used for testing the ”xbee_type”
conditional” on page 73.
Capability Bitmap specification
Advanced addressing; that is, the ability to send and ZB_CAP_ADV_ADDR=0x00000001
receive to any endpoint and cluster ID on remote nodes.
Without advanced addressing, only a single endpoint
and cluster ID (for example a remote serial port) can be
used on each node.
Ability to access XBee device objects ZB_CAP_ZDO=0x00000002
Ability to access Digi device objects on remote nodes. ZB_CAP_REMOTE_DDO=0x00000004
DDO access to the gateway radio is always available.
Ability to update firmware on the gateway radio. ZB_CAP_GW_FW=0x00000008
Ability to update firmware on remote nodes via the ZB_CAP_REMOTE_FW=0x00000010
gateway.
Supports XBee mesh networking ZB_CAP_ZIGBEE =0x00000020
Supports XBee Pro/2007 mesh networking ZB_CAP_ZBPRO=0x00000040
Supports DigiMesh networking ZB_CAP_DIGIMESH=0x00000080
Supports parent/child relationship ZB_CAP_CHILDREN 0x00000100
Supports XBee Smart Energy profile ZB_CAP_SE=0x00000200
3.4.2.4 field
each state parameter of the gateway radio. These are the same values returned by the XBee
command.
3.5
is used to set the temporary state of the device. is usually a rare command
since it is not used to set device configuration (see ) but rather is used to set the transient
or running state of the system. Examples of include setting the current time on a device, or
setting the current output voltage of a GPIO pin.
The format of the groups returned by is the same as for .
3.5.1 Attributes
None.
183.6
returns the device to default settings. It can be considered a special case of the
command.
The definition of factory defaults is left to the device implementer.
If the source=”defaults” attribute is supported on , executing
must take action that matches the settings returned by source=”defaults”.
A list of groups may optionally be provided as children to . If any groups are
present, only those groups will be factory defaulted. If a device does not support group level defaults,
the device must detect that groups have been specified and must return an appropriate error indicating
that the group-wise factory default is not supported and no action was taken. This must also be
documented in the RCI descriptor (by not specifying any child elements of .
Attention! Executing this command can have unintended side effects and its use must be
considered dangerous. For example, Device Cloud server information will most likely not be default
information that is saved. Therefore, executing this command through Device Cloud will cause the
device to lose connection to the server and local action will be required to recover.
3.6.1 Attributes
3.6.1.1 action
This attribute modifies the behavior of the command in the specified manner.
This attribute is only valid for full commands; that is, this attribute is ignored if
any groups are specified as children of the command).
Values include:
• “factory”: The command will take effect immediately and the device will
reboot immediately.
• “revert”: The command will reset stored configuration to defaults, but
current settings are not changed. Changes take effect on the next boot.
• “erase_user_flash”: All device configuration is reset to factory defaults in NVRAM. In addition,
all user flash is erased. All files will be erased including: python programs, all customization files
including custom defaults, and all XBee firmware files stored in the file system. Only on-board
NVRAM is erased. USB drives are not erased.
The default is action=”factory”.
3.7
Reboot the device immediately after replying to this RCI request.
3.7.1 Attributes
None.
193.8
is a wrapper command. It passes its contents to a sub-system specified by the target
attribute. It is commonly used for file system commands, XBee or ZigBee commands, and for passing
commands to user-created targets, for example by dynamically registering a target in a Python program.
The content of the is completely determined by the target. The only limitation is that it
must be well-formed XML and must adhere to the limitation set forth in this specification. However, any
data, including binary data, may be passed inside a by encoding it in base-64.
All static targets supported on a device must be documented in the RCI descriptor.
If a device supports dynamically registered targets, its descriptor will document a target value of “*”:
3.8.1 Attributes
3.8.1.1 target
Specifies the sub-system or entity that receives the enclosed command. target is required and there is
no default.
203.9
The variant is an interface to manipulate the file system on a
device. There are several subcommands:
• : Lists information about the contents of a directory or file.
• : Returns the contents of a file as a base-64-encoded block.
• : Uploads the contents of a file as a base-64-encoded block.
• : Deletes a file.
If a device supports more than one volume, for RCI purposes, the volumes should be considered
mounted to a root dir: “/” and listing of “/” returns all volumes available. Directories are specified with
leading slashes (“/”). If a path has a trailing slash, the path must specify a directory. If no trailing slash is
specified, the path may be a file or a directory. The Backward slash (“\”) character is not allowed.
3.9.1 subcommand
Lists information about the contents of a directory or a file.
3.9.1.1 Example request and reply
3.9.1.2 Attributes
3.9.1.2.1 path
The directory or file to list. Note that an older version of the command used “dir” instead of
“path.” For backward compatibility, devices should honor “dir” as a synonym for path on requests.
This is applicable to requests only. “dir” is always used in responses.
3.9.1.2.2 hash
Return the hash of the file contents for each file in this path. The hash can be any of the following:
• crc32: CRC-32-IEEE 802.3 hash of the contents of the file.
• md5:md5 sum of the contents of the file.
• none: No hash requested. This is the default.
If a device supports the hash attribute, it must support crc32 and may support md5.
3.9.1.2.3
On the ls element, dir is the directory that is being listed.
Note: Some earlier RCI implementations do not list subdirectories.
213.9.1.2.4
Specifies information about a file in a directory. Information may include the following:
• name: Name of the file.
• size: File size in bytes.
• hash: Hash of file, if hash was requested.
• : Subdirectory. Only the name of directory is returned.
• name: Name of sub-directory.
3.9.2 subcommand
Returns the contents of a file as a base-64-encoded block.
3.9.2.1 Example request and reply
223.9.4 subcommand
Deletes a file.
3.9.4.1 Example request and reply
233.10
This variant is an interface to interact with an XBee network. The device must contain
an XBee RF module.
3.10.1 RCI subcommands available and features on an XBee gateway
The following RCI subcommands and features are available on an XBee gateway:
• : Perform an XBee network discovery
• : Update firmware on XBee RF module on the gateway or an XBee node
• < get_lqi >: Get the neighbor table and link quality information from an XBee ZB or SE RF
module.
• : List configuration settings for an XBee node.
• : List state parameters for an XBee node.
• : Sends an arbitrary command to an XBee RF module and get the command’s
result.
• : Reset parameters for an XBee RF module to their factory default values.
• : Change parameters for an XBee RF module.
• On the , the conditional custom name “xbee_type”
Each XBee command is contained within a ; for example:
Note: target=“zigbee” is an alias for target=“xbee”
...
3.10.2 Support for XBee-related RCI subcommands
Only the command is supported on nodes that are not XBee nodes. In addition, remote XBee
nodes must support remote DDO (Digi Data Object) commands to be able to support the remote
commands. For more information, see the Product Manuals for XBee RF modules.
Standard ZigBee nodes, including third-party ZigBee nodes, also support .
Support for the following commands depends on firmware version running in the device and the XBee
module type and firmware level for the XBee RF module installed in the device. See RCI descriptors
section on page 41 for details of the following commands specific to your firmware.
243.10.3 subcommand
performs a discovery operation for the XBee network. Information returned includes:
• All nodes on the XBee network, including all remote XBee nodes and any non-XBee nodes. If a
discovery operation finds a ZigBee node that is not an XBee node, a limited subset of
information about that node is returned.
• Identity information for each node.
• On networks and firmware that support XBee firmware updates, the status of XBee firmware
update status.
The device caches information for all devices on network. The time elapsed since the device’s last
contact with a node is returned in . In addition, there are optional attributes on the
command that allow the user to clear the device’s cache. These attributes are described in
the Device Cloud Programming Guide.
In addition to the device’s cache, Device Cloud caches discovery results (along with setting and state
results) for XBee networks, just as it does for device state and settings. The server cache can be
retrieved via an SCI request specifying . To retrieve the device cache
(and update the server’s cache) specify non-cached: . See the
Device Cloud Programming Guide for more information.
253.10.3.1 Example request and reply
0
00:13:a2:00:40:0a:3e:db!
0x0
0xfffe
0xc105
0x101e
0x30001
Node name
5252
[Applies to XBee ZB only]
0x1941
0x2163
Up to date
XB24-ZB_2163.ebl
01:23:45:67:89:ab:cd:ef!
0
Error detail
0
...
263.10.3.2 Attributes
All attributes are optional.
3.10.3.2.1 addr
The 64-bit extended address of a single node to return. If addr is not given:
3.10.3.2.2 start
The node number, starting with 1 and incrementing.
3.10.3.2.3 size
The maximum number of nodes to return.
If none of these values are specified, the command returns all XBee nodes.
3.10.3.2.4 option
One of the following:
• "current" : Get node list without performing a discovery,
• "discover": Discover new nodes
• "clear": Clear previous list and discover new nodes.
If the value of start is greater than 1 or addr is specified, the default option value is "current".
Otherwise, the default for option is "discover".
273.10.4 subcommand
schedules an XBee firmware update on a device. The target for the firmware update can
be the XBee RF module on the gateway, or the XBee RF module on a remote XBee node.
For firmware updates for the XBee RF module in a gateway, this command can be used to update
firmware for any XBee RF module type.
For firmware updates for remote nodes, this command can be used for these XBee RF module tyupes
only:
• XBee ZB
• XBee 865/868LP
• XBee 900HP node types.
Devices with an XBee ZB RF module can be updated over the air. For details on performing over the air
firmware updates, see the gateway’s User’s Guide and the Product Manual for the XBee RF module in
the gateway,.
Use the XBee discover subcommand to check the status of firmware updates.
3.10.4.1 Example request and reply
3.10.4.2 Attributes
3.10.4.2.1 file
The name or full path to the firmware image file.
3.10.4.2.2 target
Optional. A 64-bit extended device address of node to update. The default target is the XBee RF module
on the gateway.
3.10.4.2.3 updater
Optional. A 64-bit extended device address of the updater node; that is, the XBee node that will serve as
the XBee firmware updater for the target. The default updater is determined automatically. For more
information on using an updater node, see the Product Manual for the XBee RF module in the gateway
and search on the keyword updater.
This option is used for firmware updates for XBee ZB RF module only. Any node type can be updated in
the gateway.
283.10.5 subcommand
returns the neighbor table information and link quality information in the Link Quality
Indicator (LQI) table from an XBee ZB or XBee SE RF module or a standard ZigBee node.
3.10.5.1 Example request and reply
01:23:45:67:89:ab:cd:ef!
01:23:45:67:89:ab:cd:ef!
01:23:45:67:89:ab:cd:ef!
0x1234
child
off
end device
no
2
255
...
0
...
3.10.5.2 Attributes
3.10.5.2.1 addr
Optional. A 64-bit extended node address. The default is to return all nodes.
For descriptions of the values returned in the neighbor and Link Quality Index tables, refer to the ZigBee
standard.
293.10.6 subcommand
returns configuration settings for an XBee node. Settings are those radio parameters
that can be changed by the command.
3.10.6.1 Example request and reply
value
...
3.10.6.2 Attributes
3.10.6.2.1.1 addr
Optional. A 64-bit extended device address for a node. The default device is the XBee RF module on the
gateway.
3.10.7 subcommand
Returns state parameters for an XBee node.
3.10.7.1 Example request and reply
value
...
3.10.7.2 Attributes
addr: Optional. A 64-bit extended device address. The default device is the XBee RF module on the
gateway.
303.10.8 subcommand
sends an AT command to an XBee RF module and gets the command’s result. For
the list of AT commands that can be entered and their parameters, see the AT commands section of the
XBee RF module’s Product Manual. Any number of elements can be specified under
a single . However, is not allowed under other commands, such as
.
3.10.8.1 Example request and reply
parameter
result
313.10.8.2 Attributes
3.10.8.2.1 id
Required. A two-character radio command.
3.10.8.2.2 format
Optional. Specifies how to interpret the data specifid by the parameter attribute. Possible options are: :
"integer": 123456 (32 bits, default)
"address": 01:23:45:67:89:ab:cd:ef! (64 bits)
"binary": 0x123abc (any length)
"string": ASCII (any length)
3.10.8.2.3 addr
Optional. A 64-bit extended device address. The default device is the XBee RF module on the.
3.10.8.2.4 timeout
Optional. The number of milliseconds to wait for a response. The default depends on the network.
3.10.8.2.5 option
Optional. Specifies how to apply the changes to the XBee RF module. Options are:
"apply": Apply changes immediately (default),
"queue" Queue changes in XBee RF module.
To apply queued changes, send a command with id="AC" or option="apply".
To save changes to radio NVRAM, send a command with id="WR".
3.10.8.2.6 parameter
Optional. The data to send with command, if any.
3.10.8.2.7 result
The data returned from command, if any, in same format as request.
result is an element if a parameter or command error occurred.
323.10.9 subcommand
resets parameters for an XBee RF module to their factory default values.
Attention! This command should be used with great care. Generally, use of this command
results in the node leaving the network. Reconnecting the node to the network may require manual,
depending on settings in the coordinator.
3.10.9.1 Example request and reply
3.10.9.2 Attributes
3.10.9.2.1 addr
Optional. A 64-bit extended device address. The default is the XBee RF module on the gateway.
333.10.10 subcommand
changes parameters for an XBee RF module.
3.10.10.1 Example request and reply
value
...
3.10.10.2 Attributes
3.10.10.2.1 addr
Optional. A 64-bit extended device address. The default device is the XBee RF module on the gateway
radio.
343.11 RCI errors and warnings
RCI responses may contain RCI errors or warnings to indicate that a requested command did not
complete normally.
Message type Description
An error occurred and the operation failed.
An RCI command was executed, but a warning was issued. Changes were
made, but not all requested changes were successful.
More than one error or warning may be present in a reply. The location of the or tag
implies the scope of the error. The parent element of or is the source of the
error/warning. For example, in this RCI code, a command experienced an error and the
command failed to execute. The caller can assume that none of the requested changes
occurred.
Operation unavailable
The following example shows that an error occurred while setting the group. An error under
implies that no changes were made to the group, even if baud is the only invalid field;
that is, group level sets are treated atomically. Note also that the element was returned
without an error, so the set was successfully applied.
Invalid baud”
baud
35This example shows the same situation, except a is returned instead of an error. This
indicates to the caller that the group was changed as requested, but a problem was
encountered and the changes may not be as expected. Again, the requested set was
successful.
Invalid baud
baud
This example shows a similar error, except that the is more precisely placed as a child of the
field. Note, however, that since the field encountered an error, the entire serial group
does not get saved. Generally, if an error occurs inside a setting group, the entire group is not saved.
The command is special in this way. Usually, if an occurs as a child of a command
(or any descendent) the command fails and changes do not take place.
Invalid baud
363.11.1 Error and warning attributes
and support the following attributes.
3.11.1.1 id
A numeric ID uniquely identifying the error. Error IDs are scoped to a named error group. If no named
error group is specified, then the error is scoped to the element to which the error is a child.
3.11.1.2 from
An error_group name to which the id attribute is scoped. The error_group is defined in the descriptor as
a set of errors that can be returned at that level and all children of that level on which it is declared.
Therefore, if an is declared as a child of , that ID and error_group name are
valid and can be returned by any setting group in the command. See RCI descriptors on
page 41 for more information.
3.11.2 Error and warning tags
and tags support the following child elements.
3.11.2.1 desc
An error description for this error, suitable for displaying to a user. This field is optional. The intention
of it being optional is to allow for an error to be returned in RCI specifying only an ID. The caller can then
look up that id in the RCI descriptor and find the description that corresponds to the error ID. However,
it is recommended that desc is returned with the error.
3.11.2.2 hint
Optional. Context-sensitive additional information that would help specify the error. A typical use is to
return the offending field name when an error is detected in a command. For example:
Insufficient permissions
rci_user
This error indicates that a command failed (whatever command is the parent to the tag), and
the specific error was error id=”3” from the error_group named “setting_errors”. The text for the error
is “Insufficient permissions,” and the error-specific hint was “rci_user”, which for this error indicates the
user ID that was used to attempt the set command.
374 RCI device implementers’ notes
The command and the compare_to and source attributes, if implemented, must
handle internal_defaults as a valid value. internal_defaults should be treated identically to defaults for
most implementers.
internal_defaults is reserved for server use and is not valid for use by general RCI clients.
385 Legacy RCI
The following RCI information concerns the original RCI implementation in Digi devices. It is included
here for completeness only.
5.1 RCI over HTTP
The primary transport is HTTP, through the embedded web server. The web server will provide the
initialization, receiving and sending, and security.
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. Any
requests larger than 32 KB 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. See the samples shipped with devices for examples of RCI
over HTTP RCI.
Standard HTTP errors will be returned for HTTP related problems. Common HTTP errors that should be
handled by clients, for example:
413 – Buffer too large. Usually caused by sending a request
larger than 32KB in size.
395.2 RCI over serial
RCI requests can be sent over the serial port, known as RCI over serial. This option is useful in scenarios
where a master processor is connected to the Digi device through a serial port. It 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. The RCI over Serial option is available only on the
primary port of the Digi device.
You must enable 'RCI over Serial' in either the Digi device’s web or command line before the Digi device
will accept RCI requests and return replies.
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.
5.2.1 Configure RCI over serial from the command-line interface (CLI)
1. Access the command-line interface using telnet or rlogin and the module's IP address. For example:
telnet 192.168.1.2
-or-
rlogin 192.168.1.2
2. At the command prompt, type:
#> set rciserial state=on
5.2.2 Configure RCI over serial from the web interface
1. Access the web interface by entering the module’s IP address in a browser’s URL window.
2. Choose Serial Ports from the Configuration menu.
3. If the device has more than one port, select Port 1.
4. If a port profile has not been selected, select Custom and click Apply.
5. Select Advanced Serial Settings.
6. Select Enable RCI over Serial (DSR) and click Apply.
40You can also read
