HOW TO: Declare multiple targets in a Device Cloud /ws/sci Request

Introduction

Digi Device Cloud is a Machine-to-Machine Cloud-based network operating platform that contains a number of useful API (Application Programmer Interface) options.  The Device Cloud APIs allow programmatic access to various aspects of the devices and gateways which are Connected to Device Cloud.  A common feature to most API requests of the Device Cloud is the need to declare a <target> to run the Request on, whether that <target> is a single device, a Group of devices, or all devices found under a customer's account.  As for how many targets can be specified in a single SCI request, this article will help to answer that question.


What is /ws/sci ?

/ws/sci (Server Command Interface) is a web service that allows users to access information and perform commands which relate to their Device Cloud connected devices. Examples of these requests include:
 

• Retrieve live or cached information about your device(s)
• Change settings on your device(s)
• Interact with a Python program running on your device(s) to send commands or retrieve information
• Read from and write to the file system on your device(s)
• Update your Python applications
• Retrieve data stored locally on your device(s)
• Update device firmware
• Update XBee radio firmware on your device(s)
• Remotely reboot your device(s)

SCI operations can be performed synchronously or asynchronously.

• Synchronous requests - useful if you would like to execute a short request to the server, and block until the operation is completed.
• Asynchronous requests - 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'll receive a response with an ID, that you can later use to check on the job status, and retrieve the results.

An SCI request is composed of XML that is POSTed to https://<Device Cloud hostname>/ws/sci.


Anatomy of an SCI Request

An SCI request uses a specific format:

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

operation_name is either send_message, update_firmware, disconnect, or query_firmware_targets

targets will specify one or more of the following elements:  <device id="{device_id}"/>, <device_id="all"/>, <device tag="{tag name}, or <group path="{group name}"/>

payload is dependent on the operation being performed
.


File Reference:

The payload for an SCI command can also be referenced from a file in Device Cloud Data Services, as opposed to being explicitly described in the actual request. For example, the following SCI request’s payload is being referenced instead of explicitly declared in the XML:

<sci_request version="1.0">
    <send_message>
        <targets>
            <device id="00000000-00000000-00000000-00000000"/>
        </targets>
        <file>/~/my_commands/set_settings.xml</file>
    </send_message>
</sci_request>

Where the content of set_settings.xml could be similar to the following:

<rci_request>
   <set_setting>
      <query_setting>...<query_setting>
   </set_setting>
</rci_request>


Example:  Here is an example SCI Request where the embedded XBee module firmware version of four different Gateway <targets> is being queried simultaneously:

<sci_request version="1.0">
  <send_message>
    <targets>
      <device id="00000000-00000000-00409DFF-FF012345"/>
      <device id="00000000-00000000-00409DFF-FF123456"/>
      <device id="00000000-00000000-00409DFF-FF234567"/>
      <device id="00000000-00000000-00409DFF-FF345678"/>
    </targets>
    <rci_request version="1.1">
      <do_command target="RPC_request">
        <xbee_AT synchronous="true">
          <command type="string">VR</command>
        </xbee_AT>
      </do_command>
    </rci_request>
  </send_message>
</sci_request>


More about Targets

As mentioned above, the target of an SCI request can be one or more elements.  Each element specified with <targets> can be thought of as an OR statement, thus you can specify multiple group paths, and it will effect each path specified.  Here are the current <targets> options available:

• <device id="{device_id}"/>

• <device id="all"/>

• <device tag="{tag name}"/>

• <group path="{group name}"/>

Note: Each element under Targets can be thought of as an OR statement, thus you can specify multiple group paths, and it will effect each path specified.


How to optimize SCI requests to avoid Device Cloud Throttles:

For information about the types of Throttles used on Digi Device Cloud, click here.

The way to get around Device Cloud throttling of your SCI request is to use a single request to target a larger group of devices.

Example:  A single request which targets a subset of a dozen devices with <device tag="{tag name}"/> of "test" would be treated as 1 request by "Throttle" logic, while sending a  request which targets each of the dozen Devices individually with <device id="{device_id}"/> would be considered 12 requests.  See the difference?


Additional Reading

The information provided above is available in the Device Cloud Programmer Guide.

It is beyond the scope of this article to describe the rich feature-set of Device Cloud and its API.  Please refer to the documentation at the link above for further information.