SCI

From Digi Developer

Jump to: navigation, search

Contents

Introduction

SCI (Server Command Interface) is an interface of Device Cloud that allows users to access information and perform commands that relate to their device. Examples of these requests include retrieving and setting configuration parameters, updating firmware, retrieving and updating files, working with XBee devices, and others.

The operations can be performed synchronously or asynchronously. Synchronous requests are useful if you would like to execute a short request to the server and block until the operation is completed. Asynchronous requests are useful when you want to execute a request that has the possibility of taking a while to complete, or you simply want to send the request off and return immediately. With asynchronous requests, you will receive an id that you can later use to check on the job status and retrieve results.

An SCI request is composed of XML that is POSTed to http(s)://{idigi-platform-url}/ws/sci


In addition to the information provided in this article, a useful reference will be the Web Services Reference under the documentation section of http://developer.idigi.com

Example Request

The following examples will be based on URLs that are appropriate if you are using Device Cloud server at http://developer.idigi.com

Synchronous

Sending the request and getting the response

POST the following to http://developer.idigi.com/ws/sci

<sci_request version="1.0"> <!-- common to every sci request -->
  <send_message> <!-- indicates we want to send an rci request -->
    <targets> <!-- preparing us for the list of who to operate on -->
      <device id="00000000-00000000-00409DFF-00000000"/> <!-- we will send it to this device -->
    </targets> 
    <rci_request version="1.1"> <!-- the payload for the send_message command, an rci request -->
      <query_state><device_stats/></query_state>
    </rci_request>
  </send_message>
</sci_request>

which will return when the operation has completed (or timed out) and the body of the response will be:

<sci_reply version="1.0"> <!-- start of the sci response -->
  <send_message> <!-- the "operation" of our sci_request -->
    <device id="00000000-00000000-00409DFF-FF374CD3"> <!-- contains the response for this device -->
      <rci_reply version="1.1"> <!-- the rci response for the particular device -->
        <query_state>
          <device_stats>
            <cpu>36</cpu>
            <uptime>152</uptime>
            <datetime>Thu Jan 1 00:02:32 1970 (based on uptime)</datetime>
            <totalmem>8388608</totalmem>
            <usedmem>5811772</usedmem>
            <freemem>2576836</freemem>
          </device_stats>
        </query_state>
      </rci_reply>
    </device>
  </send_message>
</sci_reply>

Asynchronous

Sending the request and getting a job id

POST the following to http://developer.idigi.com/ws/sci

<sci_request version="1.0"> <!-- common to every sci request -->
  <send_message synchronous="False"> <!-- the "operation" with an attribute specifying it will be asynchronous -->
    <targets> <!-- preparing us for the list of who to operate on -->
      <device id="00000000-00000000-00409DFF-00000000"/> <!-- we will send it to this device -->
    </targets> 
    <rci_request version="1.1"> <!-- the payload for the send_message command, an rci request -->
      <query_state><device_stats/></query_state>
    </rci_request>
  </send_message>
</sci_request>

which will return without waiting for the request to complete, and return an in the body as:

<sci_reply version="1.0">
  <send_message>
    <jobId>883492</jobId>
  </send_message>
</sci_reply>

Using the id to check on status

Perform an HTTP GET at http://developer.idigi.com/ws/sci/883492

which returns the job status and available results:

<sci_reply version="1.0">
  <status>complete</status>
  <send_message>
    <device id="00000000-00000000-00409DFF-FF374CD3">
      <rci_reply version="1.1">
        <query_state>
          <device_stats>
            <cpu>36</cpu><uptime>152</uptime>
            <datetime>Thu Jan  1 00:02:32 1970 (based on uptime)</datetime>
            <totalmem>8388608</totalmem>
            <usedmem>5811772</usedmem>
            <freemem>2576836</freemem>
          </device_stats>
        </query_state>
      </rci_reply>
    </device>
  </send_message>
</sci_reply>

Anatomy of an SCI Request

Every SCI request looks like the following:

<sci_request version="1.0">
  <{operation_name}>
    <targets>
      {targets}
    </targets>
    {payload}
  </{operation_name}>
</sci_request>

operation_name is either send_message, update_firmware, or disconnect

targets contains one or more elements that look like: <device id="{device_id}"/>

payload is dependent on the operation

Available Operations

Three main operations are currently available. This include send_message, update_firmware, and disconnect. 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.


There are a few attributes that can be specified for an operation that can tweak 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 means that everything should be saved. (default) errors implies that only errors in the response should be kept, while success messages should be stripped. none means that result data for the operation should be stripped.

errors is useful if you are performing an operation and only want to be 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 bunch of data in the reply, this would accomplish that.


synchronous determines whether the request should be synchronous (default), or asynchronous (if 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


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


waitForReconnect mode requests are a way to allow the completion status of an SCI command to depend on a device connect.

For instance, performing a reboot command without specifying waitForReconnect="true" causes an immediate return of success or failure. This is counter-intuitive since we may expect the completion status to depend on the device fully reconnecting.

Use with caution, as many commands do not directly result in a disconnect/reconnect to occur.


allowOffline requests enable you to send a request to a disconnected device via an SCI request. If the device is already connected, it will process the request right away. If the device is not connected, it will process the request as soon as the device connects.


send_message

This is used to send an RCI request to a device. For more information, see RCI Requests

One of the main uses of RCI requests are to interact with the settings and state of a device. The Device Cloud 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>

update_firmware

This is used to update the firmware of one or more devices.

The data for the firmware image is base64 encoded and included with the request. 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 looks like:

<sci_request version="1.0">
  <update_firmware>
    <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-00409DFF-000000">
      <submitted/>
    </device>
  </update_firmware>
</sci_reply>

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-00409DFF-FF374CD3">
      <disconnected/>
    </device>
  </disconnect>
</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-00409DFF-FF374CD3">
      <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 a currently a restriction such that the maximum retrieval size is 512KB. 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, and crc32. any is used to indicate the device should choose its best available hash. md5 or crc32 may be specified but the device may not support them (or possibly any hash mechanism at all).

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>

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.

A request follows this format:

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

data_service

A data service command is used to send a data service request to a device. The target on the device is specified, and the payload can be specified as plain text or base64 encoded. If it is base64 encoded and the format flag is set appropriately, the payload will be decoded before it is sent on to the device. This allows for binary data to be sent without the device having to decode it.


The command consists of a requests element with a child device_request, with the text of the element indicating the payload. The following attributes apply to device_request:

target_name is required and indicates the target on the device which will receive this request.

format is optional, and if set to base64 indicates that the payload should be base64 decoded before being sent to the device.


A request follows one of the following formats:

<sci_request version="1.0">
  <data_service>
    <targets>
      {targets}
    </targets>
    <requests>
      <device_request target_name="myTarget"> 
        my payload string
      </device_request>
    </requests>
  </data_service>
</sci_request>
<sci_request version="1.0">
  <data_service>
    <targets>
      {targets}
    </targets>
    <requests>
      <device_request target_name="myBinaryTarget" format="base64">
        YmluYXJ5ZGF0YS4uLg==
      </device_request>
    </requests>
  </data_service>
</sci_request>

Asynchronous Operations

Overview

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.

Performing an asynchronous request

An 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 http://developer.idigi.com/ws/sci/{job_id}

and you will get a response like:

<sci_reply version="1.0">
  <status>{current_status}</status>
  <{operation_name}>
    {available results}
  </{operation_name}>
</sci_reply>

where

current_status can be new, in_progress, complete, canceled

and the rest looks like it would for any other sci_reply, with any available results included.

Overall Status

Do an HTTP Get on http://developer.idigi.com/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>&lt;rci_request&gt;&lt;query_setting/&gt;&lt;/rci_request&gt;</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

Cancel a request

Do an HTTP DELETE on http://developer.idigi.com/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 stop starting.

Personal tools
Wiki Editing