How to Install and Update Plug-ins for Digi Smart Energy Gateways
Transcription
How to Install and Update Plug-ins for Digi Smart Energy Gateways
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