RPC Requests and Responses¶
The gateway communicates via XML-encoded RPC requests and responses. These messages are sent within an RCI wrapper that specifies the RCI target on the gateway (an example RCI target is “RPC_request”). Requests and responses are routed through Device Cloud, which specifies an SCI wrapper around the RCI message indicating which gateway or gateways to send to. Each RPC request can optionally be synchronous, meaning the gateway will block until the response is ready, and then immediately return the response. By default, RPC requests are asynchronous, meaning responses are cached locally on the gateway and must be explicitly requested. The gateway can also be configured to push asynchronous responses to the Device Cloud server as files.
In order to communicate with the gateway, XML requests must be generated along with RCI/SCI wrappers to address the correct device. It is outside the scope of this document to cover methods for generating and parsing XML, sending requests to the gateway, or communicating with the Device Cloud server from within a custom application. Digi-SE Debug Console can be used to communicate with the gateway through Device Cloud. Or see http://www.digi.com/wiki/developer/index.php/SCI for more information on sending SCI requests to Device Cloud.
Synchronous Requests and Responses¶
Here is an example of sending a synchronous get_time request to two gateways:
<sci_request version="1.0">
<send_message>
<targets>
<device id="00000000-00000000-001122FF-FF334455"/>
<device id="00000000-00000000-001122FF-FF334456"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<get_time synchronous="TRUE"/>
</do_command>
</rci_request>
</send_message>
</sci_request>
The responses from multiple devices will be accumulated into a single SCI response by Device Cloud. Because the request above is a synchronous request, the response message will contain the actual RPC response:
<sci_reply version="1.0">
<send_message>
<device id="00000000-00000000-001122FF-FF334455"/>
<rci_reply version="1.1">
<do_command>
<responses remaining="0" timestamp="1234567890.0">
<get_time_response timestamp="1234567888.0"/>
<UTC_2000>0x133FDDDD<UTC_2000>
<UTC_1970>0x4BAD215D<UTC_1970>
</get_time_response>
</responses>
</do_command>
</rci_reply>
</device>
<device id="00000000-00000000-001122FF-FF334456"/>
<rci_reply vesion="1.1">
<do_command>
<responses remaining="0" timestamp="1234567890.0">
<get_time_response timestamp="1234567888.0"/>
<UTC_2000>0x133FDDDD<UTC_2000>
<UTC_1970>0x4BAD215D<UTC_1970>
</get_time_response>
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
Note
While a synchronous request is being processed by a gateway, no other RPC requests can be handled by that gateway. New requests will be queued until the synchronous response has been generated.
Note
The <responses> tag has a “remaining” attribute which indicates how many messages are in the gateway’s asynchronous response message buffer.
Asynchronous Requests¶
Here is an example of sending the same get_time request asynchronously:
<sci_request version="1.0">
<send_message>
<targets>
<device id="00000000-00000000-001122FF-FF334455"/>
<device id="00000000-00000000-001122FF-FF334456"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<get_time/>
</do_command>
</rci_request>
</send_message>
</sci_request>
The immediate responses to asynchronous requests will be empty:
<sci_reply version="1.0">
<send_message>
<device id="00000000-00000000-001122FF-FF334455"/>
<rci_reply version="1.1">
<do_command/>
</rci_reply>
</device>
<device id="00000000-00000000-001122FF-FF334456"/>
<rci_reply vesion="1.1">
<do_command/>
</rci_reply>
</device>
</send_message>
</sci_reply>
When the response is generated by the gateway it will be stored in the gateway’s asynchronous response buffer.
Note
The size of the asynchronous response buffer is controlled by Registry Settings.
Before 1.5.0: The maximum number of messages is limited by the RPC_Manager.max_buffer_items setting.
As of 1.5.0: The maximum size of the buffer in bytes is limited by the RPC_Manager.max_buffer_length setting.
Note
The asynchronous response buffer is not power safe. If power safety for asynchronous responses is critical, you can have the gateway push the responses to the Device Cloud server, where they will be stored as files; see Automatic Response Pushing.
As of 1.5.0: There is a configuration option to store un-sent message to flash when Automatic Response Pushing is enabled. This can be configured using a registry setting (see RPC_Manager.store_to_flash_delay in Registry Settings)
Retrieving Asynchronous Responses¶
To retrieve asynchronous response messages from the gateway, send to the “RPC_response” target. Here is an example of retrieving asynchronous responses from a single gateway:
<sci_request version="1.0">
<send_message>
<targets>
<device id="00000000-00000000-001122FF-FF334455"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_response">
<get_responses/>
</do_command>
</rci_request>
</send_message>
</sci_request>
The reply to an RPC_response request contains a listing of asynchronous RPC messages in chronological order, starting with the oldest message. Every response will contain a timestamp attribute indicating when it was generated. Here is an example, with the response to the get_time request as well as an unrelated asynchronous message:
<sci_reply version="1.0">
<send_message>
<device id="00000000-00000000-001122FF-FF334455"/>
<rci_reply version="1.1">
<do_command>
<responses reamining="0" timestamp="1234567895.0">
<get_time_response timestamp="1234567885.0"/>
<UTC_2000>0x133FDDDD<UTC_2000>
<UTC_1970>0x4BAD215D<UTC_1970>
</get_time_response>
<message timestamp="1234567890.0">
<description type="string">You must bring us another shrubbery.</description>
<severity>0x1</severity>
</message>
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
Note
The <responses> tag has a “remaining” attribute which indicates how many messages are in the gateway’s asynchronous response message buffer following the get_responses operation. Typically this will be 0 unless a limit on the number of responses is imposed (see Asynchronous Response Limits).
In order to correlate asynchronous requests and responses, it is recommended that the standard parameter “request_identifier” be used. This parameter may be of any data type. For example, here is an asynchronous request using a request identifier:
<sci_request version="1.0">
<send_message>
<targets>
<device id="00000000-00000000-001122FF-FF334455"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<get_time>
<request_identifier>1</request_identifier>
</get_time>
</do_command>
</rci_request>
</send_message>
</sci_request>
Requesting asynchronous responses some time later would result in:
<sci_reply version="1.0">
<send_message>
<device id="00000000-00000000-001122FF-FF334455"/>
<rci_reply version="1.1">
<do_command>
<responses reamining="0" timestamp="1234567895.0">
<get_time_response timestamp="1234567885.0"/>
<request_identifier>1</request_identifier>
<UTC_2000>0x133FDDDD<UTC_2000>
<UTC_1970>0x4BAD215D<UTC_1970>
</get_time_response>
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
Multiple Commands in a Single RCI request¶
You may include multiple RPC commands within a single RCI command. These commands will be processed in sequence. Note that many of the gateway’s operations are internally asynchronous, which may effectively result in the commands being executed simultaneously. Here is an example for synchronously requesting multiple AT parameters from the gateway’s XBee radio:
<sci_request version="1.0">
<send_message>
<targets>
<device id="00000000-00000000-001122FF-FF334455"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<xbee_AT synchronous="true">
<command type="string">SC</command>
</xbee_AT>
<xbee_AT synchronous="true">
<command type="string">HV</command>
</xbee_AT>
<xbee_AT synchronous="true">
<command type="string">VR</command>
</xbee_AT>
</do_command>
</rci_request>
</send_message>
</sci_request>
In the case of synchronous requests, the gateway will wait until all responses are ready before generating the response message:
<sci_reply version="1.0">
<send_message>
<device id="00000000-00000000-001122FF-FF334455"/>
<rci_reply version="1.1">
<do_command>
<responses remaining="0" timestamp="1234567890.0">
<xbee_AT_response timestamp="1234567888.0"/>
<command type="string">SC</command>
<value>0xFF</value>
</xbee_AT_response>
<xbee_AT_response timestamp="1234567889.0"/>
<command type="string">HV</command>
<value>0x1A44</value>
</xbee_AT_response>
<xbee_AT_response timestamp="1234567890.0"/>
<command type="string">VR</command>
<value>0x3326</value>
</xbee_AT_response>
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
Synchronous Timeouts¶
A synchronous response of some kind will always be generated after a certain amount of time has passed so that the system does not block indefinitely. This may result in some synchronous requests timing out. If the responses to those requests are later generated by the gateway, they will be treated as asynchronous responses. This timeout is settable (see Registry Settings). Note that Device Cloud has a timeout of its own, so making the gateway’s timeout too large will result in no response of any kind being received when a synchronous request times out.
In order to correlate synchronous requests and timeouts, it is recommended that the standard parameter “request_identifier” be used. This parameter may be of any data type. Here is an example using request identifiers:
<sci_request version="1.0">
<send_message>
<targets>
<device id="00000000-00000000-001122FF-FF334455"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<xbee_AT synchronous="true">
<request_identifier>1</request_identifier>
<command type="string">SC</command>
</xbee_AT>
<xbee_AT synchronous="true">
<request_identifier>2</request_identifier>
<command type="string">HV</command>
</xbee_AT>
<xbee_AT synchronous="true">
<request_identifier>3</request_identifier>
<command type="string">VR</command>
</xbee_AT>
</do_command>
</rci_request>
</send_message>
</sci_request>
Here is the response where one of the requests has timed out:
<sci_reply version="1.0">
<send_message>
<device id="00000000-00000000-001122FF-FF334455"/>
<rci_reply version="1.1">
<do_command>
<responses remaining="0" timestamp="1234567890.0">
<xbee_AT_response timestamp="1234567858.0"/>
<request_identifier>1</request_identifier>
<command type="string">SC</command>
<value>0xFF</value>
</xbee_AT_response>
<xbee_AT_response timestamp="1234567859.0"/>
<request_identifier>2</request_identifier>
<command type="string">HV</command>
<value>0x1A44</value>
</xbee_AT_response>
<message timestamp="1234567890.0"/>
<request_identifier>3</request_identifier>
<description type="string">Synchronous request timed out.</description>
<severity>0x2</severity>
</message>
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
Asynchronous Response Limits¶
The gateway has a maximum number of asynchronous messages that can be stored. Requesting asynchronous messages from the gateway will clear them from the list of stored messages. If more messages are generated than can be stored, the oldest messages will be dropped. See RPC_Manager in Registry Settings.
If necessary, when retreiving asynchronous responses a limit can be set on the number of messages returned by specifying the “limit” attribute. The oldest messages will be retrieved first.
<sci_request version="1.0">
<send_message>
<targets>
<device id="00000000-00000000-001122FF-FF334455"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_response">
<get_responses limit="10"/>
</do_command>
</rci_request>
</send_message>
</sci_request>
Automatic Response Pushing¶
The gateway can be configured to push asynchronous responses immediately to the Device Cloud server as files (see Registry Settings). Responses pushed in this manner will be cleared from the gateway’s asynchronous response buffer. This is useful if polling the gateway to retrieve asynchronous messages is not desired, or if power safety of asynchronous messages is required.
Note
Response messages wil not be removed from the gateway’s asynchronous response buffer until they have been successfully pushed to the Device Cloud server. Responses can still be retrieved via “RPC_response” if pushing does not succeed for any reason.
File Format¶
Each pushed file contains a single response without an RCI or SCI wrapper. Here is an example of file contents:
<message timestampe="1234567890.0">
<description type="string">You must bring us another shrubbery.</description>
<severity>0x1</severity>
</message>
The filename is formatted with the following information:
- pushed file prefix (defaults to “RPC_response”)
- timestamp
- sequence number
- response tag
- file extension (defaults to “xml”)
The sequence number differentiates responses pushed in the same second. Here are some example filenames:
RPC_response-1234567890-0000-message.xml
RPC_response-1234567890-0001-get_version_response.xml
RPC_response-1234567890-0002-get_device_information_response.xml
RPC_response-1234567897-0000-message.xml