Description: This article discusses how to discover the Device Cloud descriptors of a ConnectPort X2e for Smart Energy gateway. The contents of the article can be used to discover the descriptors of any Device Cloud connected device that supports Descriptors.
How to find the Descriptors:
Use the POST method from /ws/sci, to POST the following Device Cloud API request (where ######FF-FF###### represents your Device's actual Device ID), to find out the available Descriptor options.
Request:
<sci_request version="1.0">
<send_message>
<targets>
<device id="00000000-00000000-00409DFF-FF521118"/>
</targets>
<rci_request version="1.1">
<query_descriptor />
</rci_request>
</send_message>
</sci_request>
Response:
<sci_reply version="1.0">
<send_message>
<device id="00000000-00000000-00409DFF-FF521118">
<rci_reply version="1.1">
<query_descriptor>
<descriptor element="rci_request" desc="Remote Command Interface request">
<attr name="version" desc="RCI version of request. Response will be returned in this versions response format" default="1.1">
<value value="1.1" desc="Version 1.1"/>
</attr>
<descriptor element="query_setting" dscr_avail="true"/>
<descriptor element="set_setting" dscr_avail="true"/>
<descriptor element="set_factory_default" dscr_avail="true"/>
<descriptor element="reboot" dscr_avail="true"/>
<descriptor element="query_state" dscr_avail="true"/>
<descriptor element="set_state" dscr_avail="true"/>
<descriptor element="do_command" dscr_avail="true"/>
<error_descriptor id="1" desc="Request not valid XML"/>
<error_descriptor id="2" desc="Request not recognized"/>
<error_descriptor id="3" desc="Unknown command"/>
<error_descriptor id="4" desc="Internal error"/>
</descriptor>
</query_descriptor>
</rci_reply>
</device>
</send_message>
</sci_reply>
Finding out the current_state of this Device for instance
To find out the current status of the CP-X2e SE gateway using the available descriptors output above, we could send a POST Request for query_state:
Request:
<sci_request version="1.0">
<send_message>
<targets>
<device id="00000000-00000000-00409DFF-FF521118"/>
</targets>
<rci_request version="1.1">
<query_state />
</rci_request>
</send_message>
</sci_request>
Response:
The Response for the query_state Request above for Device ID 00000000-00000000-00409DFF-FF521118 are too lengthy to be listed within this article, but can be viewed by clicking on this link.
Finding out the descriptors for the settable options
If we wanted to find out the Descriptor options for query_setting for instance, we could send a request like the following:
Request:
<sci_request version="1.0">
<send_message>
<targets>
<device id="00000000-00000000-00409DFF-FF521118"/>
</targets>
<rci_request version="1.1">
<query_descriptor>
<query_setting/>
</query_descriptor>
</rci_request>
</send_message>
</sci_request>
Response:
The Response for the POST Request above for Device ID 00000000-00000000-00409DFF-FF521118 are too lengthy to be listed within this article, but can be viewed by clicking on this link.
Finding out how the Device is setup:
While the Request/Response output above was a query of the options for the query_setting descriptors, the Request below shows how those settings are actually set currently:
Request:
<sci_request version="1.0">
<send_message>
<targets>
<device id="00000000-00000000-00409DFF-FF521118"/>
</targets>
<rci_request version="1.1">
<query_setting />
</rci_request>
</send_message>
</sci_request>
Response:
The Response for the POST Request above are to Device ID 00000000-00000000-00409DFF-FF521118 are too lengthy to be listed within this article, but can be viewed by clicking on this link.
Conclusion:
The article above gives some idea how to find out various information from your Device Cloud connected device by querying the Device Descriptors. The same type of queries can be used to find out additional information which hasn't been covered in this article, such as information particular to your own devices provisioned on Device Cloud.
Note: The descriptors for various products are based on the level of support for Descriptors within that particular product, which is sometimes also determined by the firmware in use on the device. Please see the Digi Technical Support website for further information about whether or not firmware updates for your product.
Last updated:
Jan 08, 2024