How to Install and Update Plug-ins for Digi Smart Energy Gateways
How to Install and Update Plug-ins for Digi Smart
Energy Gateways
Document Part Number: 90001396_A
Last update: 4/23/2014
www.digi.com
How to Install and Update Plug-ins for Digi Smart Energy Gateways
What is a plug-in and why would I want it?
Smart Energy networks contain a variety of devices, including thermostats, load
controllers, smart plugs, and in-premise displays. Many of these have functions that are not
covered by the Smart Energy standard. Plug-ins, also known as drivers, are software
components that Digi provides to expose the additional common functionality for many of these
devices. For example, thermostats expose the capability to adjust set-points, set schedules,
and read the current temperature. None of these capabilities are defined in the Smart Energy
profile.
What is the plug-in manager?
The plug-in manager is a software component that extends the Smart Energy
Framework installed on your gateways. The plug-in manager also allows you to install, remove,
and query the status of installed plug-ins.
Where do I find the plug-ins?
A complete list of plug-in drivers can be found at the Digi Technical Support website.
Following is a list of several commonly-used plug-ins.
•
•
•
•
•
•
•
•
•
•
•
Plug-in Manager (PN: 82002934)
Proxy Cluster Plug-in (PN: 82002935)
Common Clusters plug-in (PN: 82002936)
Common Clusters Secure plug-in (PN: 82003232)
Thermostat Schedule plug-in (PN: 82002937)
Computime Thermostat plug-in (PN: 82002938)
Energate Z100 Thermostat plug-in (PN: 82002939)
ERT Smart Energy Bridge plug-in (PN: 82002940)
Safe Plug plug-in (PN: 82002941)
Carrier Comfort Choice Thermostat Plug-in (PN: 82003230)
Schneider EER56x00 Thermostat Plug-in (PN: 82003231)
Note: If installing the plugin(s) on a ConnectPort X2e Smart Energy Gateway, use the file(s)
from the python2.7 directory. If installing the plugin(s) on a ConnectPort X2 Smart Energy
gateway, use the file(s) from the python2.4 directory.
www.digi.com
How to Install and Update Plug-ins for Digi Smart Energy Gateways
How do I know if I need to install a plug-in?
You may need to install a plug-in on your gateway if you are not using an application
like www.livesmartlee.com. Smartlee installs plug-ins; however, it does not upgrade them, so
you may need to follow the instructions in this document to bring your plug-ins up to date.
You may also be using a custom application through a third party service provider,
instead of using Smartlee. If this is the case, you should to contact your service provider for any
required plug-in updates instead of updating the plug-ins yourself.
Digi provides the following information primarily for Digi partners and third party
providers. For any of the devices found on the following list, you must install a driver if you
want to access additional capabilities, such as scheduling or compressor runtime information.
Digi-tested Smart Energy devices which currently have driver support follows:
Manufacturer
Carrier
Computime
Computime
Digi
Energate
SafePlug
Schneider Electric
Schneider Electric
Model
ComfortTouch
CTL2182
CTL2181
50001763-02
Z100
1202
EER56100 Multi-Stage ZigBee
EER56000 Single-Stage ZigBee
Device Type
Thermostat
Thermostat
Thermostat
ERT/Meter
Thermostat
Smart Plug
Thermostat
Thermostat
What if my device is not listed?
If your device is not listed, Digi has not written a plug-in to support the device. We do
not currently suggest that you attempt to write your own plug-in. If you want Digi to add your
device to the list, please contact your Digi salesperson to request pricing for a custom driver.
www.digi.com
How to Install and Update Plug-ins for Digi Smart Energy Gateways
How to install your drivers
•
•
Smart Energy Gateway: ConnectPort X2 Smart Energy, ConnectPort X2e Smart Energy
Supported Smart Energy Device
In addition, you will need:
•
•
A Device Cloud login account (https://login.etherios.com)
The plug-in for your supported Smart Energy device
How do I install the plug-in manager?
The plug-in manager requires a Digi gateway running the Smart Energy Framework to
work properly. The following instructions use Device Cloud to update your Smart Energy
gateway.
STEP 1 - UPLOAD THE PLUG-IN MANAGER TO THE GATEWAY
1. Login using your Device Cloud account.
2. Navigate to the devices screen via Device Management -> Devices.
3. Double click the target device in the devices table.
4. Select Python from the left-hand navigation menu.
5. Click the upload file icon.
6. Upload plugin_manager.zip to the /WEB/python directory.
Note: If installing the plugin(s) on a ConnectPort X2e Smart Energy Gateway, use the
file(s) from the python2.7 directory. If installing the plugin(s) on a ConnectPort X2
Smart Energy gateway, use the file(s) from the python2.4 directory.
STEP 2 - CONFIGURE THE SMART ENERGY FRAMEWORK
1. Navigate to the API explorer via Documentation -> API Explorer.
2. Select POST in the HTTP method section.
3. Paste the following XML to the text box, replacing $deviceId with the Device Cloud
Device ID of your device.
www.digi.com
How to Install and Update Plug-ins for Digi Smart Energy Gateways
Install Plug-In Manager XML
<sci_request version="1.0">
<send_message>
<targets>
<device id="$deviceId"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<add_path synchronous="true">
<path type="string">plugin_manager.zip</path>
</add_path>
<add_module synchronous="true">
<module_name type="string">plugin_manager.interface</module_name>
</add_module>
<add_interface synchronous="true">
<interface_class type="string">Plugin_Interface</interface_class>
</add_interface>
</do_command>
</rci_request>
</send_message>
</sci_request>
How do I install a plug-in and its dependencies?
To install plug-ins, a device must be equipped with the Smart Energy Framework and
must have the plug-in manager installed. If the plug-in has dependent plug-ins, these
dependencies must be installed on the gateway first. Note that each plugin.yml file lists the
other plug-ins on which it depends. The current list of dependencies is listed in the following
table. Note: you must install all required dependencies. For example, the Carrier Comfort
Choice requires the following drivers in order: plugin_manager, proxy_cluster.
Plug-in
plugin_manager
proxy_cluster
common_clusters_secure
schedule_base
energate_z100
ertsebridge
computime_ctw
safe_plug
schneider_eer56x00
carrier_comfort_choice
www.digi.com
Requires
Start here
plugin_manager
proxy_cluster
common_clusters_secure OR
common_clusters
schedule_base,
common_clusters_secure
plugin_manager
schedule_base,
common_clusters
common_clusters
common_clusters_secure,
schedule_base
common_clusters,
schedule_base
Required for Device
--HAI Load Controller
-Energate Z100
Digi ERT/Smart Energy Bridge
Computime CTW
2D2C SafePlug
EER56100 Multi-Stage ZigBee or
EER56000 Single-Stage ZigBee,
HAI Thermostat
Carrier Comfort Choice
How to Install and Update Plug-ins for Digi Smart Energy Gateways
STEP 1 - UPLOAD THE PLUG-IN PACKAGE
1. Navigate to the devices screen via Device Management -> Devices.
2. Double click the target device in the devices table.
3. Select Python from the left-hand navigation menu.
4. Click the upload file icon.
5. Upload the plug-in package(s) to the /WEB/python directory.
STEP 2 - Install the plug-in package
1. Navigate to the API explorer via Documentation -> API Explorer.
2. Select POST in the HTTP method section.
3. Paste the following XML to the text box, replacing $deviceId with the Device ID of the
gateway and $packageName with the name of the plug-in package uploaded in Step 1.
Install package request XML
<sci_request version="1.0">
<send_message>
<targets>
<device id="$deviceId"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<install_package synchronous="true">
<filename type="string">$packageName</filename>
</install_package>
</do_command>
</rci_request>
</send_message>
</sci_request>
How do I update an existing plug-in?
1. Stop all the plug-ins and their dependent processes by running stop_plugin.
2. Uninstall the plug-in you want to update by running uninstall_plugin.
3. Update the plug-in file using Device Cloud to perform a file upload.
4. Install the new plug-in using install_package.
5. Restart all the plug-ins that you stopped in Step 1. You can also restart the plug-ins by
rebooting your device.
www.digi.com
How to Install and Update Plug-ins for Digi Smart Energy Gateways
Command Reference
This section describes some additional commands to help you manage the plug-ins
installed on your gateway. The following terms are used in this section:
•
A plug-in is enabled if it is configured to load whenever the plug-in manager starts.
•
A plug-in is active if its configuration has been loaded by the plug-in manager. A plug-in
becomes active after it is started, and inactive after it stops.
The plug-in manager exposes several RPC methods for interacting with plug-ins.
list_plugins: Gets the name and version of all plug-ins on the gateway
Request
<sci_request version="1.0">
<send_message>
<targets>
<device id="$deviceId"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<list_plugins synchronous="true"/>
</do_command>
</rci_request>
</send_message>
</sci_request>
Response
<sci_reply version="1.0">
<send_message>
<device id="$deviceId">
<rci_reply version="1.1">
<do_command target="RPC_request">
<responses>
<list_plugins_response>
<count type="int">0x1</count>
<plugins type="list">
<item type="dict">
<active type="bool">{TRUE|FALSE}</active>
<version type="string">$pluginversion</version>
<enabled type="string">{True|False}</enabled>
<plugin_name type="string">$pluginName</plugin_name>
</item>
</plugins>
www.digi.com
How to Install and Update Plug-ins for Digi Smart Energy Gateways
</list_plugins_response>
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
plugin_info: Gets the name, version, description, active state, and enabled state
Request
<sci_request version="1.0">
<send_message>
<targets>
<device id="$deviceId"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<plugin_info synchronous="true">
<plugin_name type="string">$pluginName</plugin_name>
</plugin_info>
</do_command>
</rci_request>
</send_message>
</sci_request>
Response
<sci_reply version="1.0">
<send_message>
<device id="$deviceId">
<rci_reply version="1.1">
<do_command target="rpc_request">
<responses>
<plugin_info_response>
<active type="bool">{TRUE|FALSE}</active>
<version type="string">$pluginVersion</version>
<enabled type="string">{True|False}</enabled>
<description type="string">$pluginDescription</description>
<plugin_name type="string">$pluginName</plugin_name>
</plugin_info_response>
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
install_package: Installs a plug-in from a zip file onto the gateway
Request
<sci_request version="1.0">
www.digi.com
How to Install and Update Plug-ins for Digi Smart Energy Gateways
<send_message>
<targets>
<device id="$deviceId"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<install_package synchronous="true">
<filename type="string">$filename</filename>
</install_package>
</do_command>
</rci_request>
</send_message>
</sci_request>
Response
<sci_reply version="1.0">
<send_message>
<device id="$deviceId">
<rci_reply version="1.1">
<do_command target="RPC_request">
<responses>
<install_package_response>
<plugin_name type="string">$pluginName</plugin_name>
<version type="string">$pluginVersion</version>
<active type="bool">{TRUE|FALSE}</active>
<enabled type="string">{True|False}</enabled>
</install_package_response>
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
uninstall_plugin: Uninstalls a plug-in from the gateway
Request
<sci_request version="1.0">
<send_message>
<targets>
<device id="$deviceId"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<uninstall_plugin synchronous="true">
<plugin_name type="string">$pluginName</plugin_name>
</uninstall_plugin>
</do_command>
</rci_request>
</send_message>
</sci_request>
Response
<sci_reply version="1.0">
<send_message>
www.digi.com
How to Install and Update Plug-ins for Digi Smart Energy Gateways
<device id="$deviceId">
<rci_reply version="1.1">
<do_command target="RPC_request">
<responses>
<uninstall_plugin_response>
<plugin_name type="string">$pluginName</plugin_name>
</uninstall_plugin_respons>
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
start_plugin: Starts running a plug-in. Applies the configuration in the plugin.yml file
and calls plug-in start hooks.
Request
<sci_request version="1.0">
<send_message>
<targets>
<device id="$deviceId"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<start_plugin synchronous="true">
<plugin_name type="string">$plugiName</plugin_name>
</start_plugin>
</do_command>
</rci_request>
</send_message>
</sci_request>
Response
<sci_reply version="1.0">
<send_message>
<device id="$deviceId">
<rci_reply version="1.1">
<do_command target="RPC_request">
<responses>
<start_plugin_response>
<plugin_name type="string">$pluginName</plugin_name>
<version type="string">$pluginVersion</version>
<active type="bool">TRUE</active>
<enabled type="string">{True|False}</enabled>
</start_plugin_response>
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
www.digi.com
How to Install and Update Plug-ins for Digi Smart Energy Gateways
stop_plugin: Stops running a plug-in. Reverts the configuration in the plugin.yml file and
call plug-in's stop hooks.
Request
<sci_request version="1.0">
<send_message>
<targets>
<device id="$deviceId"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<stop_plugin synchronous="true">
<plugin_name type="string">$pluginName</plugin_name>
</stop_plugin>
</do_command>
</rci_request>
</send_message>
</sci_request>
Response
<sci_reply version="1.0">
<send_message>
<device id="$deviceId">
<rci_reply version="1.1">
<do_command target="RPC_request">
<responses>
<stop_plugin_response>
<plugin_name type="string">$pluginName</plugin_name>
<version type="string">$pluginVersion</version>
<active type="bool">FALSE</active>
<enabled type="string">{True|False}</enabled>
</stop_plugin_response>
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
enable_plugin: Starts running a plug-in, if not already started, and sets the plug-in to start
every time the plug-in manager starts
Request
<sci_request version="1.0">
<send_message>
<targets>
<device id="$deviceId"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<enable_plugin synchronous="true">
<plugin_name type="string">$pluginName</plugin_name>
</enable_plugin>
</do_command> </rci_request>
www.digi.com
How to Install and Update Plug-ins for Digi Smart Energy Gateways
</send_message>
</sci_request>
Response
<sci_reply version="1.0">
<send_message>
<device id="$deviceId">
<rci_reply version="1.1">
<do_command target="RPC_request">
<responses>
<enable_plugin_response>
<plugin_name type="string">$pluginName</plugin_name>
<version type="string">$pluginVersion</version>
<active type="bool">TRUE</active>
<enabled type="string">True</enabled>
</enable_plugin_response>
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
disable_plugin: stop running a plugin (if started) and don't start the plugin when the plugin
manager starts
Request
<sci_request version="1.0">
<send_message>
<targets>
<device id="$deviceId"/>
</targets>
<rci_request version="1.1">
<do_command target="RPC_request">
<disable_plugin synchronous="true">
<plugin_name type="string">$pluginName</plugin_name>
</disable_plugin>
</do_command>
</rci_request>
</send_message>
</sci_request>
Response
<sci_reply version="1.0">
<send_message>
<device id="$deviceId">
<rci_reply version="1.1">
<do_command target="RPC_request">
<responses>
<disable_plugin_response>
<plugin_name type="string">$pluginName</plugin_name>
<version type="string">$pluginVersion</version>
<active type="bool">FALSE</active>
<disabled type="string">False</disabled>
</disable_plugin_response>
www.digi.com
How to Install and Update Plug-ins for Digi Smart Energy Gateways
</responses>
</do_command>
</rci_reply>
</device>
</send_message>
</sci_reply>
www.digi.com