HOW TO: Run Smart Energy Framework RPC commands from Digi Device Cloud Web Services

Introduction:

The ConnectPort Smart Energy Gateways (CP-X2 SE, CP-X2e SE, CP-X4 SE IA) and the ERT/Ethernet Gateway all use a python application called the Smart Energy Framework (aka SEF or SE Framework).  While the Gateway's OS type, Python version, or SE Network roles may vary, their common purpose as a Gateway is to IP-enable the data coming in from the RF network, then push it to Device Cloud at regular intervals.

Once on Device Cloud, this information can be accessed from anywhere in the world, regardless of the underlying hardware architecture which originally provided the data. But how does one configure the Smart Energy Framework python application within the Gateway from Device Cloud? Please read on....


Overview:

The commands you'll send via Device Cloud to the Gateway's SE Framework API will vary depending on the task you want to accomplish at the time, but the basic procedure remains the same.  In the example below, you'll be taking two of the RPC commands from the SE Framework API, then executing them on your remote Gateway via Device Cloud Web Services.

The Smart Energy Framework is the python application running on your Digi ERT or Smart Energy Gateway, which serves as the "glue" between the remote Gateway's RF network and the Cloud.  The application also contains an Application Programmer's Interface (API) for configuring various aspects of the RF network and the traffic seen on it, as you'll see below.

Note:  The ERT/Ethernet Gateway is not a ZigBee Smart Energy device, but formats the ERT bubble-up data it receives into ZCL Simple Metering Cluster format for purposes of monitoring consumption.  The Smart Energy-like EUI-64 address which the Gateway uses is actually a "cooked" address based on the Gateway's Ethernet MAC address.


Requirements:

1. A Digi gateway running the Smart Energy Framework
   (CP-X2 for Smart Energy, CP-X2e for Smart Energy, or ERT/Ethernet Gateway)
2. Access to a Device Cloud account, where the Gateway above is currently in a Connected state
3. The Device Cloud account (free or subscribed) must contain a Smart Energy Management subscription

To learn about the API of the Smart Energy Framework python application, the best place to start is the Smart Energy Developer Tools website:



Login with your Device Cloud account credentials for the server which the account containing your Gateway is found on.  Once logged in, the User Guide link would take you straight into the SE Framework API documentation, but an even better way to get there is to select the Debug link from the top menu and access the Debug Console instead.

Important Note:  Messages seen in the Output section (right side of window) at this point are messages which came into your Gateway since the last reboot.  The messages should be expanded and examined for potential error messages which might indicate a problem on the network.  Success indicators will also appear, in order to verify the network is functioning and all devices have been discovered.  

Hit the Refresh button at the Debug Console to pull in the current command set of your Gateway (beware: this will also clear the buffer of the Output window section mentioned above - save any traffic if needed before hitting Refresh).




Procedure:

The following exercise will take you through finding the API commands to get the SE Framework and Xbee firmware versions from your Gateway, then running these commands from the Device Cloud API Explorer.

1. From the Debug tab, select RPC_General_Interface API from the Command menu on the left.
2. Click the link for get_version to populate command example in the Input area as follows:
   
   <get_version synchronous="true">
     <module_name type="string">Version</module_name>
   </get_version>
    
3. Now select RPC_ZigBee_Interface from the Command menu
4. Click the link for xbee_AT (a new tab opens in the Input area), then replace the value in the example with "VR" as follows:
   
   <xbee_AT synchronous="true">
     <command type="string">VR</command>
   </xbee_AT> 
    
5. Open another tab or browser window, then Login to the Device Cloud account where your Gateway is found.
6. Once logged into Device Cloud, select the Documentation tab, then API Explorer sub-tab.
   
   Note:  All SE Framework XML-RPC API commands (such as those shown above) can be run from Device Cloud --- API Explorer when formatted into SCI/RCI do_commands like in the following example:
     <sci_request version="1.0">
     <send_message>
       <targets>
         <device id="00000000-00000000-00409DFF-FF######"/>
         <device id="Insert additional lines per unique device ID/Gateways"/>
       </targets>
       <rci_request version="1.1">
         <do_command target="RPC_request">
           Insert RPC XML commands here
         </do_command>
       </rci_request>
     </send_message>
   </sci_request>
   
   Note:  RPC do_commands on Device Cloud will produce an error message Response if any of the four requirements mentioned earlier were not met, or a device being addressed in your request does not exist in an Active state on your network.
    
7. In the API Explorer, select Path as /ws/sci, and HTTP Method as POST.
8. Copy/Paste the following into the Console window and modify as necessary for your particular Gateway and/or command(s):
   
     <sci_request version="1.0">
     <send_message>
       <targets>
         <device id="00000000-00000000-00409DFF-FF######"/>
       </targets>
       <rci_request version="1.1">
         <do_command target="RPC_request">
           <get_version synchronous="true">
             <module_name type="string">Version</module_name>
           </get_version>
           <xbee_AT synchronous="true">
             <command type="string">VR</command>
           </xbee_AT>
         </do_command>
       </rci_request>
     </send_message>
   </sci_request>
    
9. Run the SCI/RCI RPC do_command by pressing the Send button, which will produce a Response similar to the following (version numbers may vary):
   
   

The procedure outlined above can be used to run any valid API command of the Smart Energy Framework python application. This can be very useful when doing a   ConnectPort X2e for Smart Energy (Router) Installation, or adding a Reporting configuration once the Gateway has Joined successfully.

Additional Resources:

Smart Energy Framework and ERT User Guide - SE Framework API documentation
Smart Energy RF Product Manual - AT commandset used with the xbee_AT RPC command
Device Cloud User Guide - User Guide for your Device Cloud account
Device Cloud Programming Guide - Commands usable from Device Cloud Web Services