Asynchronous Requests
SCI requests that are asynchronous return without waiting for the request to finish, and return a job ID that can be used to retrieve the status and results later.
If you POST an SCI request asynchronously and want to see the results, the general flow is:
POST the SCI request.
if rc=202 // The job is accepted
get the location from the response header or the job ID from the response content
rc = HEAD location
while rc!=200
sleep for a number of seconds
rc = HEAD location
GET location
process your results
DELETE location
A synchronous request is performed by specifying synchronous=“false” in the element specifying the operation in the request, e.g.: <send_message synchronous="false">
the response then has the form:
<sci_reply version="1.0">
<send_message>
<jobId>{job_id}</jobId>
</send_message>
</sci_reply>
where job_id identifies the request you submitted.
Retrieve Status
You can retrieve the status for a particular request, or retrieve information about submitted requests overall.
Status for a Particular Job
Do an HTTP GET on /ws/sci/{job_id}
To determine if a job is complete, do an HTTP HEAD specifying the job ID; /ws/sci/601358. A return code of 200 means the job is complete.
Overall Status of Outstanding Jobs
Do an HTTP GET on /ws/sci, and you will get a response that looks like:
<result>
<resultTotalRows>1</resultTotalRows>
<requestedStartRow>0</requestedStartRow>
<resultSize>1</resultSize>
<requestedSize>1000</requestedSize>
<remainingSize>0</remainingSize>
<Job>
<jobId>601358</jobId>
<cstId>0</cstId>
<usrId>0</usrId>
<jobType>0</jobType>
<jobSyncMode>0</jobSyncMode>
<jobReplyMode>0</jobReplyMode>
<jobTargets>00000000-00000000-0004F3FF-00000000</jobTargets>
<jobRequestPayload><rci_request><query_setting/></rci_request></jobRequestPayload>
<jobDescription>query_setting</jobDescription>
<jobStatus>2</jobStatus>
<jobTargetCount>1</jobTargetCount>
<jobProgressSuccess>1</jobProgressSuccess>
<jobProgressFailures>0</jobProgressFailures>
<jobSubmitTime>2010-03-02T15:36:22Z</jobSubmitTime>
<jobCompletionTime>2010-03-02T15:36:22Z</jobCompletionTime>
</Job>
</result>
where jobId is the ID for the request.
jobType is the type of the job (0: send_message, 1: update_firmware, 2: disconnect).
jobSyncMode indicates if the job is synchronous (0: synchronous, 1: asynchronous).
jobReplyMode indicates the reply mode (0: all, 1: none, 2: only), where only means only return errors.
jobStatus is the current status of the job (0: new, 1: in_progress, 2: complete, 3: canceled).
jobTargetCount is the number of devices the job is targeted for.
jobProgressSuccess is the number of devices that have completed the operation successfully.
jobProgressFailures is the number of devices that have completed the operation with an error.
Retrieve Progress
You can retrieve the progress for a particular SCI job by specifying the progress=true parameter. For example:
HTTP GET https://remotemanager.digi.com/ws/sci/{job_id}?progress=true
This will return the current progress (percent completion) for an SCI job, as well as its progress history. For example, let’s assume we have an SCI job that is performing a firmware update on two different devices. Performing the query shown above will give a response that looks something like:
<sci_reply version="1.0">
<status>in_progress</status>
<update_firmware>
<device id="00000000-00000000-000000FF- FF000001">
<progress time="Mon Nov 28 21:30:25 UTC 2011" status="0">Getting Target Info</progress>
<progress time="Mon Nov 28 21:30:27 UTC 2011" status="0">Sending Download Request</progress>
<progress time="Mon Nov 28 21:31:15 UTC 2011" status="5">Sending Data: 156672 out of 3130662 bytes sent</progress>
<progress time="Mon Nov 28 21:32:07 UTC 2011" status="10">Sending Data: 313344 out of 3130662 bytes sent</progress>
</device>
<device id="00000000-00000000-000000FF- FF000002">
<progress time="Mon Nov 28 21:30:26 UTC 2011" status="0">Getting Target Info</progress>
<progress time="Mon Nov 28 21:30:27 UTC 2011" status="0">Sending Download Request</progress>
<progress time="Mon Nov 28 21:31:05 UTC 2011" status="5">Sending Data: 156672 out of 3130662 bytes sent</progress>
<progress time="Mon Nov 28 21:31:48 UTC 2011" status="10">Sending Data: 313344 out of 3130662 bytes sent</progress>
<progress time="Mon Nov 28 21:32:30 UTC 2011" status="15">Sending Data: 470016 out of 3130662 bytes sent</progress>
</device>
</update_firmware>
</sci_reply>
We can also query for job progress on other types of SCI jobs, including file uploads through the File System service. Progress updates for file uploads through RCI is not supported.
Cancel a Request or Delete the Results
Do an HTTP DELETE on /ws/sci/{job id}
This will attempt to cancel the request. Some parts of the request may have already completed, and parts of the request that are in progress may continue to completion, but it should prevent any operations that have not yet begun from starting.
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, sha3-512, and crc32. Use any to indicate the device should choose its best available hash. (If you specify md5, sha-512, sha3-512, or crc32, 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>