Available Operators

Introduction

Available operators include:

send_message allows an RCI request to be sent to the device (or the server cache).

update_firmware updates the firmware of the device.

disconnect sends a request to the device to disconnect from the server.

ping determines the round trip latency of a device connection.

query_firmware_targets gets a list of firmware targets on the device.

file_system is used to interact with files on a device. This interface is for use with devices supporting the file_system service (as opposed to other devices that support file_system interaction through RCI requests.) The RCI do_command for file_system is only supported by older devices not implementing the file_system service.

data_service sends messages to devices over the data service.

reboot issues a reboot for a device.

There are a few attributes that can be specified for an operation that can specify the behavior. They include:
<{operation_name} reply="all|errors|none"> 
<{operation_name} synchronous="true|false"> 
<{operation_name} syncTimeout="xxx">
<{operation_name} cache="true|false|only">
<{operation_name} allowOffline="true|false">
<{operation_name} waitForReconnect="true|false">

reply determines how much information should be saved in the response to a request.

all (default) means that everything should be saved.

errors implies that only errors in the response should be kept, while success messages should not be saved.

none means that result data for the operation should not be saved.

errors is useful if you are performing an operation and only want to see error information that occurred, such as when setting settings, or performing firmware update. none is useful when you aren’t concerned with the reply at all. If you are performing a synchronous request because you want to wait until the operation is complete, but do not want to receive a lot of data in the reply, this would accomplish that.

synchronous determines whether the request should be sent synchronously (default), or asynchronously (false).

syncTimeout is applicable for a synchronous request and determines how long to wait for the request to complete (in seconds) before an error is returned. The default changes based on the type. The overall timeout for the SCI request will be the accumulation of all operations combined. Unless overridden with syncTimeout, the timeouts on send_message commands are as follows:

operation	timeout
default	1 min
do_command target=“file_system”	10 min
do_command target=“zigbee”	5 min
firmware update	5 min

cache determines if the request should be processed on the server if possible, or always sent to the device. Options include:

true (default) means that if possible, the request will be processed from the server cache without being sent to the device. If it cannot, it will be sent to the device.
false means that the request will bypass the server cache and be sent to the device.
only means that the request should only be processed by the server cache and will never be sent to the device, even if the server is not capable of servicing the request.

allowOffline determines if this should be an offline operation. Offline operations enable you to send a request to a device that is currently disconnected. If the device is already connected, then Remote Manager will execute the command right away. If the device is not connected, then Remote Manager will execute the command as soon as the device connects to Remote Manager. Offline requests can be specified by setting the allowOffline attribute to “true”.

NOTES:

By default, SCI requests are synchronous. For offline operations, it is recommended to use an asynchronous request by setting the synchronous attribute to “false”.
Asynchronous offline operations will timeout after 7 days.
If for some reason the device disconnects during processing, the operation will automatically be retried again the next time the device connects. Offline operations will be retried up to 5 times before failing.

waitForReconnect allows the completion of a command to depend on a device reconnecting. For example, normally sending a reboot command to a device would result in the command being marked as successfully completed as soon as the device acknowledges the reboot request. However, in many instances, it may make sense to wait to mark the command as successful until the device reconnects to Remote Manager. In such cases, this can be achieved by setting the waitForReconnect attribute to “true”.

Warning: Many commands do not result in the device disconnecting and reconnecting to Remote Manager, meaning that improper use of this setting could result in the request taking an indefinite amount of time to complete; use caution when using this setting.

send_message

This is used to send an RCI request to a device. The reply will contain the response from the devices or groups of devices, or any error messages. A device ID of all will cause the RCI request to be sent to all devices available to the user.

One of the main uses of RCI requests are to interact with the settings and state of a device. Remote Manager keeps a cache of the latest settings and state that it has received from a device, and this makes it possible to retrieve information about the state or settings of a device without having to go to the device.

The format of the send_message command is as follows:

<sci_request version="1.0">
   <send_message>
      <targets>{targets}</targets>
      <rci_request version="1.1">
         <!-- actual rci request -->
      </rci_request>
   </send_message>
</sci_request>

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 (e.g. return all settings).

set_setting

Set settings specified in setting element. Settings data required.

Empty setting groups in reply indicate success. Errors returned as error or warning elements.

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 (e.g. return all state).

Example:

<query_state>
  <device_stats/>
</query_state>

reboot

Reboots device immediately.

do_command

The do_command is a child element of an RCI Request that is executed differently based on the value of its target attribute. Note that the command may not be supported for use with your device. See the file_system service.

Python You can add callbacks to unhandled do_commands target via the rci python module on a device.

Zigbee

The zigbee rci command interacts with an xbee module.

ZigBee Discover

Returns back a list of discovered nodes, with the first indexed node being the node in the gateway.

Optional attributes:

start says the rci should return the nodes whose index is >= start. For some reason, if start > 1, the Gateway will return this list from cache, and not perform an actual discovery.
size Determines number of nodes to return
clear If this is set to “clear”, it forces a clearing of the device’s cache, and will always perform a discover to get fresh results

Example:

<do_command target="zigbee">
  <discover start="1" size="10" option="clear"/>
</do_command>

ZigBee Query Setting

Returns back a detailed list of settings for a given radio

Optional attribute:

addr 64 bit address of the node to retrieve settings for. If omitted, defaults to gateway node

Example:

<do_command target="zigbee">
  <query_setting addr="00:13:a2:00:40:34:0c:88!"/>
</do_command>

ZigBee Query State

This is identical to query_setting, except it returns back different fields.

ZigBee Set Setting

Basically the reverse of query_setting, so you can set settings for a particular node

Optional attributes:

addr 64 bit address of node to set settings for. If omitted, defaults to gateway node

Example:

<do_command target="zigbee">
<set_setting addr="00:13:a2:00:40:34:0c:88!">
     <radio>
         <field1>value1</field1>
         ...
         <fieldn>valuen</fieldn>
     </radio>
</set_setting>
</do_command>

ZigBee Firmware Update

Updates the firmware of the radio in the gateway

Required attribute:

file Path to a firmware file which must already exist on the gateway

Example:

<do_command target="zigbee">
  <fw_update file="/WEB/firmware_file"/>
</do_command>

update_firmware

This is used to update the firmware of one or more devices. The firmware image can be hosted in your Data Services directory on Remote Manager, or can be Base64 encoded and placed in a data element within the update firmware command. The response marks each device as either submitted or failed. A response of “Submitted” means the process to send the firmware and update request to Remote Manager completed successfully.

It is still possible for the process to fail between Remote Manager and the device. You will need to go back and verify that the device firmware version has actually changed. You can do this by using the DeviceCore request defined earlier. You may also use the RCI command “query_state”.

There are optional attributes filename, and firmware_target, which are included with the update_firmware element.

filename needs to be specified if your target device supports multiple targets that can be updated in order to choose which to upgrade. These will match patterns specified by the device which can be discovered using the query_firmware_targets command.

firmware_target can be used to bypass the filename matching and force an upgrade on a particular target.

A request using a Base64 encoded file looks like:

<sci_request version="1.0">
   <update_firmware filename="abcd.bin">
      <targets>{targets}</targets>
      <data>{base64 encoded firmware image}</data>
   </update_firmware>
</sci_request>

and the reply looks like:

<sci_reply version="1.0">
   <update_firmware>
      <device id="00000000-00000000-00000000-000000">
         <submitted />
      </device>
   </update_firmware>
</sci_reply>

To do the update operation with a file stored in Remote Manager Data Services, use the <file> attribute:

<sci_request version="1.0">
    <update_firmware filename="abcd.bin">
        <targets> 
            {targets} 
        </targets>
        <file>~/firmware/abcd.bin</file> 
    </update_firmware> 
</sci_request>

The above example assumes that you created a directory called “firmware” off the root of your home directory in Data Services. “~” is an alias to the home directory of your account.

disconnect

Disconnect is used to indicate that a device should disconnect from the server. Based on the device’s configuration, it will likely reconnect.

A request follows this format:

<sci_request version="1.0">
   <disconnect>
      <targets>{targets}</targets>
   </disconnect>
</sci_request>

and a response looks like:

<sci_reply version="1.0">
   <disconnect>
      <device id="00000000-00000000-00000000-00000000">
         <disconnected />
      </device>
   </disconnect>
</sci_reply>

ping

Ping is used to determine the round trip latency of a device connection. The result gives the actual time used to send a simple command to the device and receive a reply.

A request follows this format:

<sci_request version="1.0">
    <ping>
       <targets>
          <device id="00000000-00000000-00042DFF-FF04A85A"/>        
       </targets>
    </ping>
</sci_request>

The sample response contains the actual time used to send a simple command to the device and receive a reply.

<sci_reply version="1.0">
    <ping>
      <device>
             <device id="00000000-00000000-00042DFF-FF04A85A">
             <time>
             	<device units="ms">5</device>
             </time>
       </device>
    </ping>
</sci_reply>

query_firmware_targets

Query Firmware Targets is used to retrieve information about the upgradeable firmware targets of a device. It will return the target number, name, version, and code size. A pattern may also be returned in the response which indicates a regular expression that is used to determine the appropriate target for a given filename.

A request follows this format:

<sci_request version="1.0">
   <query_firmware_targets>
      <targets>{targets}</targets>
   </query_firmware_targets>
</sci_request>

and a response looks like:

<sci_reply version="1.0">
   <query_firmware_targets>
      <device id="00000000-00000000-00000000-00000000">
         <targets>
            <target number="0">
               <name>Firmware Image</name>
               <pattern>image\.bin</pattern>
               <version>7.5.0.11</version>
               <code_size>2162688</code_size>
            </target>
            <target number="1">
               <name>Bootloader</name>
               <pattern>rom\.bin</pattern>
               <version>0.0.7.5</version>
               <code_size>65536</code_size>
            </target>
            <target number="2">
               <name>Backup Image</name>
               <pattern>backup\.bin</pattern>
               <version>7.5.0.11</version>
               <code_size>1638400</code_size>
            </target>
         </targets>
      </device>
   </query_firmware_targets>
</sci_reply>

file_system

The file system command is used to interact with files on a device. This interface is for use with devices supporting the file system service (as opposed to other devices which support file system interaction through RCI requests).

Commands have the following general format:

<sci_request version="1.0">
   <file_system>
      <targets>{targets}</targets>
      <commands>{one or more file_system commands}</commands>
   </file_system>
</sci_request>

Support file system commands are as follows:

put_file

The put_file command is used to push new files to a device, or optionally write chunks to an existing file.

path is a required attribute giving the file to write to.
offset is an optional attribute specifying the position in an existing file to start writing at.
truncate is an optional attribute indicating the file should be truncated to the last position of this put.

The payload is specified in one of two ways:

Child element data with the payload Base64 encoded
Child element file with a path to a file in storage to send

Example: A put file operation using a file on the server as the source for the data. The contents will be inserted into the file /path_to/write1.ext, as offset 200. It is set to not truncate the file if it extends beyond the length of written data.

<sci_request version="1.0">
   <file_system>
      <targets>
         <device id="00000000-00000000-00000000-00000000" />
      </targets>
      <commands>
         <put_file path="/path_to/write1.ext" offset="200" truncate="false">
            <file>~/referencedfilename.xml</file>
         </put_file>
      </commands>
   </file_system>
</sci_request>

A put file with the data Base64 encoded and embedded in the request under the data element. Offset and truncate are not specified, so this example will create a new file if one does not exist, or overwrite an existing one.

<sci_request version="1.0">
   <file_system>
      <targets>
         <device id="00000000-00000000-00000000-00000000" />
      </targets>
      <commands>
         <put_file path="/path_to/write2.ext">
            <data>ZmlsZSBjb250ZW50cw==</data>
         </put_file>
      </commands>
   </file_system>
</sci_request>

get_file

The get_file command is used to retrieve a file from the device, either in its entirety or in chunks. There is currently a restriction such that the maximum retrieval size is 10MB. As a result, files greater than this size will have to be retrieved in chunks.

path is a required attribute giving the file to retrieve.
offset is an optional attribute specifying the position to start retrieving from.
length is an optional attribute indicating the length of the chunk to retrieve.

Example: The get file in this example will retrieve 64 bytes starting at offset 100 from the file /path_to/file.ext. Leaving off offset and length would cause the full file to be retrieved.

<sci_request version="1.0">
   <file_system>
      <targets>
         <device id="00000000-00000000-00000000-00000000" />
      </targets>
      <commands>
         <get_file path="/path_to/file.ext" offset="100" length="64" />
      </commands>
   </file_system>
</sci_request>

ls

The ls command is used to retrieve file listings and details.

path is a required attribute specifying where to get file details for.
hash is an optional attribute which indicates a hash over the file contents should be retrieved. Values include none, any, md5, sha-512, and sha3-512. Use any to indicate the device should choose its best available hash. (If you specify md5, sha-512, or sha3-512, the device may not support the hash or any hash mechanism).

Example: This ls request will return a listing of the contents of /path_to_list. By specifying hash=“any”, the response will include the most optimal hash available, if any. Leaving off the hash attribute will default it to none.

<sci_request version="1.0">
   <file_system>
      <targets>
         <device id="00000000-00000000-00000000-00000000" />
      </targets>
      <commands>
         <ls path="/path_to_list" hash="any" />
      </commands>
   </file_system>
</sci_request>

rm

The rm command is used to remove files.

path is a required attribute specifying the location to remove.

Example: This rm request will attempt to delete /path_to/file.ext

<sci_request version="1.0">
   <file_system>
      <targets>
         <device id="00000000-00000000-00000000-00000000" />
      </targets>
      <commands>
         <rm path="/path_to/file.ext" />
      </commands>
   </file_system>
</sci_request>

data_service

A new subcommand in SCI is now supported to send messages to a device over the data service. The command element is data_service, and it must contain an element requests. The requests element contains a device_request element, with required attribute target_name and optional attribute format. target_name specifies the data service target the request will be sent to. The text data contained in the device_request element is used as the payload for the request. If format is not specified, the content will be sent as text. If format=“base64” is specified, the content will be Base64 decoded and sent to the target as a binary payload.

Example of text payload

<data_service>
   <targets>
      <device id="00000000-00000000-00000000-00000000" />
   </targets>
   <requests>
      <device_request target_name="myTarget">my payload string</device_request>
   </requests>
</data_service>

Example of binary payload

<data_service>
   <targets>
      <device id="00000000-00000000-00000000-00000000" />
   </targets>
   <requests>
      <device_request target_name="myBinaryTarget" format="base64">YmluYXJ5ZGF0YS4uLg==</device_request>
   </requests>
</data_service>

reboot

Reboot is used to issue a reboot for a device. The majority of devices may not support this operation, and will instead support reboot through RCI. This option exists as an alternative for devices that may not support RCI.

Example:

<reboot>
   <targets>
      <device id="00000000-00000000-00000000-00000000" />
   </targets>
</reboot>

Available Operators

Table Of Contents

Introduction

send_message

query_setting

set_setting

query_state

reboot

do_command

update_firmware

disconnect

ping

query_firmware_targets

file_system

put_file

get_file

ls

rm

data_service

reboot