ConnectPort X2 for Smart Energy User’s Manual 90001120_F SE_Framework version 1.3.0.
©Digi International Inc. 2010. All Rights Reserved. The Digi logo is a registered trademarks of Digi International, Inc. Digi Connect, Connectware Manager, ConnectPort, Digi SureLink, are trademarks of Digi International, Inc. All other trademarks mentioned in this document are the property of their respective owners. Information in this document is subject to change without notice and does not represent a commitment on the part of Digi International.
Contents Overview .............................................................................. 1 ZigBee Smart Energy ..............................................................................3 Description ......................................................................................3 Advantages .....................................................................................3 ConnectPort X2 for Smart Energy ...........................................................4 Description ..........
In-Premise Display .................................................................35 Meter ......................................................................................39 General Operation............................................................. 40 Startup Sequence ..................................................................................41 Remote Device Management ................................................................42 Device Detection ....................................
remove_interface..............................................................65 add_endpoint....................................................................66 remove_endpoint..............................................................67 add_cluster .......................................................................67 remove_cluster .................................................................68 get_version.......................................................................69 help..........
updated_active_DRLC_events (response only) ...............99 get_message_events .....................................................100 create_message_event ..................................................100 cancel_message_event..................................................101 cancel_all_message_events ..........................................102 received_message_confirmation (response only) ..........103 received_message_event (response only).....................
CancelLoadControlEventRecord ....................................126 CancelAllLoadControlEventsRecord ..............................127 ReportEventStatusRecord..............................................127 GetScheduledEventsRecord ..........................................127 DisplayMessageRecord .................................................128 CancelMessageRecord ..................................................128 MessageConfirmationRecord .........................................
Overview CONTENTS This document provides an introduction to Digi's Smart Energy Framework and explains how to use the framework to set up a ConnectPort X2™ running Python® code to implement a ZigBee® Smart Energy™ Gateway, how to use its provided samples, and details about its operation and XML RPC interface. DROPIN NETWORKING As an integral part of the Drop-in Networking strategy, the Python development environment is incorporated by Digi into each gateway.
QUESTIONS? For technical assistance with your Drop-in Network, call: 1-800-903-8430 (US Only) Digi contact numbers outside US Country Toll Free Number Argentina 00-800-3444-3666 Australia 0011-800-3444-3666 Brazil 0021-800-3444-3666 China North 00-800-3444-3666 China South 00-800-3444-3666 France 00-800-3444-3666 Germany 00-800-3444-3666 Hong Kong 001-800-3444-3666 India 000-800-100-3383 Israel 00-800-3444-3666 Italy 00-800-3444-3666 Japan For calls from KDD fixed land-line phones:
ZIGBEE SMART ENERGY Description The ZigBee Smart Energy Profile defines a wireless home area network (HAN) to manage energy in residential areas. These networks are local to the home and connect through a gateway back to the Utility head-end application. The current devices defined for Smart Energy are: • • • • • • • • Meter - Reports consumption of energy, water, gas, etc. Energy Service Interface (ESI) - Gateway from the Utility head-end to the HAN.
CONNECTPORT X2 FOR SMART ENERGY Description The Digi ConnectPort X2 for Smart Energy is a gateway on a Smart Energy network that provides secure access to a ZigBee Smart Energy network over the internet. The gateway is set up to take advantage of connection management services offered by the iDigi™ platform, and to intelligently handle SE events in order to reduce the need for communication and micro management by utility applications.
• • during low demand times at night. Pricing can be set in real time to respond to demand or ahead of time to allow customers to plan energy usage. Messaging server - Sends messages to a customer through ZigBee network. Messages can require confirmation from the customer. Metering client - Reads the metering usage data from meters on the network.
Network Diagram This diagram shows the role of a Gateway within an Advanced Metering Infrastructure (AMI) network.
RESOURCES The following resources are referred to throughout this User’s Manual. This page is intended to be a convenient reference. The following download is available at www.idigi.com. • Python - version 2.4.3 (follow link to Python site) Downloads Go to www.digi.com/X2SE or click on the link to download the following: • • • Digi Device Discovery Application (http://ftp1.digi.com/support/utilities/40002265_G.exe) ZB to Smart Energy (SE) Conversion Kit (http://ftp1.digi.
• ZigBee Smart Energy Profile Specification, ZigBee Document 075356r15.
Getting Started CHAPTER 1 Upon completion of the Getting Started section you will be able to: • • • • • Create an account on iDigi.com Configure your gateway Connect your gateway to iDigi.com Communicate with the gateway's RPC API through iDigi Add other devices to the gateway's network The ConnectPort X2 for Smart Energy Starter Kit includes an XStick SE. You may also convert an XStick ZB, Digi XBee USB adapter, or other serially-attached XBee to SE.
PRODUCT COMPONENTS, REQUIREMENTS, AND RESOURCES Product Components PC Requirement You will also need: A personal computer, connected to the Internet.
Additional Products To run the In-Premise Display/Meter Simulator sample (see page 30), you will also need one of the following devices that has been converted to SE firmware. Full instructions and firmware can be found in the ZB to SE conversion kit, which can be downloaded from www.digi.com/X2SE or by clicking this link: http://ftp1.digi.com/support/images/zbto-smart-energy-conversion-kit.zip. • XBee-PRO ZB USB adapter with internal wire antenna (part number XA-Z14CE1P-A).
SET UP IDIGI AND GATEWAY Introduction to iDigi The iDigi Platform is a network management solution that provides easy integration for M2M (Machine-to-Machine) and mesh networking devices. iDigi is based on a cloud computing model that provides for on-demand scalability and high-availability. It lowers the barriers to building secure, scalable, cost-effective solutions that seemlessly tie together enterprise applications and remote devices regardless of their location or network.
Create an Account on iDigi.com To get started, set up an account on the iDigi Platform as follows. 1. Navigate to http://www.idigi.com. 2. Click on the iDigi Platform Login button.
3. If you already have an account enter your user credentials in the User Name and Password fields, then click the Log on button. For new users, click on the "Are you a new user" link and create your account.
Configure the Gateway Connect and Power on the ConnectPort X2 1. Unpack the ConnectPort X2 for Smart Energy gateway. 2. Connect the power supply to the X2 gateway and connect the power supply to an electrical outlet. Note: (International version only): Connect the power supply to a power cable (not included), and the power cable to an outlet. 3. Connect an Ethernet cable from the gateway to your hub or switch that provides access to the Internet. Point Gateway to developer.idigi.
5 Python thread 6 Python thread #> #> kill 1 Connection 1 : killing connection ... Now that the process is killed, you can type “who” again to see that the gateway is currently waiting (in this case, for ten seconds) to retry the server connection, which is now pointed to the correct server, developer.idigi.com. #> who ID From To 1 wait 0:00:10 waiting to connect 2 3 Protocol idigi wait Python: main.py 10.8.16.
2. In the Devices list, click the button to bring up the Add Devices dialog.
3. Locate and select your device from the list of locally discovered devices and click the ‘OK’ button. If your device was not found in the list, check that it is turned on and connected to the same local network as your PC and click the ‘Refresh’ button. Adding your device through automatic discovery informs iDigi about the device and configures that device to connect to the iDigi Connectivity server.
6. Your device information will load into a separate tab.
ADD DEVICES TO THE ZIGBEE SE NETWORK The Google App sample may be used to send RPC requests to the gateway. (See “iDigi SE Web Sample, Communicating with Gateway” on page 24.) Please read this section first if you do not have a means of sending RPC requests to the gateway. Additionally, the In-Premise Display/Meter Simulator sample may be used to simulate devices to add to your network. (See “In-Premise Display/Meter Simulator Sample” on page 30.
Add Device to Trust Center Gateway In order to add a device to the Smart Energy network with the X2 gateway running as a trust center (ESI coordinator), use the add_device RPC request (see “add_device_response Parameters:” on page 73). This will add a device with the given link key or installation code to the device table stored in the ESI. Joining will be enabled for the specified amount of time (set in this example to 600 seconds).
All of the parameters are optional. The response will give the current value for everything but the link key and the installation code.
This is our local device -
- 0x5E
(See “Power_Desc_rsp” on page 118 for parameters.
- 0x5E
(See “Power_Desc_rsp” on page 118 for parameters.) 0x1 1397 77:66:55:44:33:22:11:00 (See “Node_Desc_rsp” on page 117 for parameters.
IDIGI SE WEB SAMPLE, COMMUNICATING WITH GATEWAY Overview This sample provides a simple demonstration of a system which communicates with a ConnectPort X2 for Smart Energy through iDigi using the RPC interface. Because this sample provides generic access to the RPC interface, it may be used to communicate with the gateway for other samples and development. How to Use this Sample 1. Go to www.idigi-se.appspot.com. 2. Enter your iDigi username and password and click Login.
3. On the Options window, select the device ID of your gateway and click Save.
4. On the Debug Console page, messages sent by the gateway will appear in the output window. If the gateway has just been turned on, some initialization messages may be displayed in the window.
5. Query the gateway for available commands by clicking the Refresh Command List button. This will populate the command list.
6. Select a command from the list and modify parameters as necessary. Click Execute.
XML requests and responses will appear in the output window and can be expanded by clicking on them.
INPREMISE DISPLAY/METER SIMULATOR SAMPLE Overview This sample simulates the basic functionality of a Smart Energy In-Premise Display or Meter with an XBee attached to a personal computer such as an XStick, XBee USB adapter, or other serially-attached XBee. It can be used to demonstrate Smart Energy functionality when real SE IPDs and meters are not convenient or available. If you do not already have one of these devices they may be purchased from the Digi website.
5. Select the COM port and baud rate of your serially-attached XBee and click Open COM Port. The Baud rate is shown below as 115200 but will commonly need to be set to 9600 after following instructions in the ZB to SE Conversion Kit.
6. Load the test certificate information that corresponds to the serially-attached XBee. This can be accomplished in two ways: Load Cert From File a. Click Load Cert From File. b. Select the test certificate file that corresponds to the EUI field under XBee Settings and click Open.
Manual Entry a. Manually enter the CA Public Key, Implicit Cert and Private Key. 7. Write the Certificate to the serially-attached XBee by clicking Write Certificate. 8. Enter a 128-bit hex value of your choosing into the Link Key field and click Set Link Key to write the link key to the serially-attached XBee.
9. Enable joining on the trust center and register the link key / installation code of the XBee. If using an ESI coordinator, send an add_device RPC request to the gateway in order to allow the serially-attached XBee to join the gateway's network. Set the parameters of the request to correspond to the serially-attached XBee and to enable joining. 10. Click Attempt to Join Network and wait until XBee Status indicates that the XBee has joined with the network.
Network View The Network tab provides a convenient overview of all endpoints and clusters of devices which have been detected on the network. The information displayed should closely match the information returned by a get_device_information RPC request sent to the gateway (see “get_device_information” on page 74). To detect new devices, endpoints and clusters click Partial Refresh. To clear and rediscover all known device information, click Full Refresh.
ZCL attributes can be read and written from the Network Tab after selecting an attribute. In-Premise Display To create an In-Premise Display endpoint, go to the In-Premise Display tab and click the Enable In-Premise Display check box. This will create Price, Messaging and Simple Metering client clusters on a new endpoint on the simulated device. The sample will display the price from any price servers on the network.
The price event will automatically be sent to all known Price client clusters. You should see the new price value appear. If there is an Aux Gateway on the network, it should receive the price event and return a “received_price_event” (see “received_price_event on page 114) response and an “updated_active_price_event” (see “updated_active_price_event” on page 114), assuming there was not another price event with a matching issuer_event_id.
The message event will automatically be sent to all known Messaging client clusters. You should see the new message appear. If there is an Aux Gateway on the network, it should receive the message event and return a “received_message_event” (see “received_message_event” on page 104) response and an “updated_active_message_event” (see “updated_active_message_event” on page 105).
Additionally, if a Simple Metering server cluster is found on the network, the current usage information will be automatically retrieved and displayed via ZCL reporting.
Meter To create a Metering Device endpoint, go to the Meter tab and click the Enable Meter check box. This will create a Simple Metering server cluster on a new endpoint on the simulated device. You may set the meter to either have a fixed usage value or a linearly increasing value.
CHAPTER 2 General Operation The following section describes the standard initialization, automation, and configuration features of the gateway.
STARTUP SEQUENCE The following operations are performed in order by the gateway when powered on. 1. Core modules are imported and core objects are initialized. The gateway will then load the modules and objects specified in the configuration files (see “Global Saved Files” on page 48). All RPC requests are now registered and available for use. Be aware that some RPC requests require time to be synchronized and / or the gateway to be joined to a network and may return errors. 2.
REMOTE DEVICE MANAGEMENT Device Detection A remote device is detected when one of the following happens: • • A ZigBee message is received by the gateway from that device. A ZigBee message is successfully sent to that device from the gateway.
Transmission Retries and Device Inactivity A remote device is considered inactive if a certain number of sequential transmissions to that device fail (see “ZDO_Device_Manager.max_sequential_TX_failures” on page 46). When a remote device is marked as inactive, clusters on the gateway will be informed that any matching clusters on the remote device are no longer available.
ZCL Reporting and Device Activity If ZCL attribute reporting is configured on the gateway to expect reports from an active remote device, and that device has not sent a report within the configuration’s timeout setting, the reporting configuration will be resent to the remote device. The remote device may have had a power loss or other fatal error and so lost its reporting configuration. ZCL attribute reports will not be sent to a device which is inactive.
REGISTRY The registry is created when the gateway first boots and contains power-safe global settings to control gateway behavior. Individual entries can be accessed and modified through the registry_configuration RPC request. A help RPC request can be used to retrieve the entire registry. If necessary, manually editing registry_settings.ini and rebooting is possible but not recommended. Settings and Defaults Registry Setting Default Description Conversation.
Registry Setting Default Description 1 If a message is generated by the firmware with severity greater than or equal to this value, it will be sent as an RPC response. Default to all warnings and errors. RPC_Manager.max_buffer_items 250 Up to this many outgoing RPC responses will be stored by the gateway before the oldest response is discarded. RPC_Manager.pushed_file_extension xml If pushing is enabled, this string will be used as the file extension of the pushed file.
Registry Setting Default Description ZDO_Device_Manager.require_explicit_device_add FALSE If TRUE, devices must be explicitly added before they can become active. If FALSE, devices can become active without being explicitly added. If not specified, the gateway will use its default behavior. (See “Explicit Device Add and Open Join” on page 43.) Cluster.disable_APS_encryption FALSE If TRUE, APS encryption checks for clusters which normally require encryption will be ignored.
POWER SAFETY Certain information is automatically saved to flash in order to maintain gateway functionality in case of a power failure. Global Saved Files The gateway stores the following files under /WEB/python/ for persistent configuration and startup behavior. These files can be viewed through iDigi, the web interface, or built in file system commands of the gateway. File Description registry_settings.ini Stores the current state of the registry settings for the gateway.
File endpoints.ini Description Specifies additional endpoints to be instantiated on startup. Optional parameters default to the class definition. (See “add_endpoint” on page 66 and “remove_endpoint” on page 67.) Format: endpoint_class_name endpoint_id [profile_id [device_id [device_version]]] Sample: SE_EnergyServicePortal 0x5E This will instantiate an Energy Service Portal on endpoint 0x5E on startup. clusters.ini Specifies additional clusters to be instantiated on startup for a given endpoint.
CHAPTER 3 Communication Protocol The following section explains the basics of communicating with the gateway when it is running the SE framework. An API reference for all RPC requests and responses can be found in “Appendix A” on page 63. BASIC COMMUNICATION OVERVIEW The gateway communicates via XML encoded RPC requests and responses. These messages are sent within an RCI wrapper that specifies the RPC target.
RPC Request and Response Example RPC requests and responses are contained in an RCI wrapper, which specifies the command target (i.e. “RPC_request”). This RCI wrapper is contained in an SCI wrapper, which specifies devices to which the commands will be sent. Here is an example to send a synchronous get_time request and an asynchronous get_version request to two gateways:
The responses from multiple devices will be accumulated into a single SCI response by iDigi. The reply to the above example would look like the following: PAGE 62The reply to an RPC_response request contains a listing of RPC responses in chronological order. By default timestamps are enabled and every response will indicate when it was generated. The top level “responses” tag will also indicate how many response messages remain in the gateway’s buffer. For example: You must bring us another shrubbery.
Automatic Response Pushing The gateway can be configured to push responses immediately to the iDigi server instead of the default polling mode via RPC_response. (See “RPC_Manager.use_push” on page 46.) Memory on the gateway is limited and it can be advantageous to store responses on the iDigi server to avoid the risk of dropping messages if too many responses are generated. Note: Response messages will not be removed from the gateway’s buffer until they have been successfully pushed to the iDigi server.
XML RPC INTERFACE OVERVIEW Conversion to Method Call XML RPC requests convert into method calls on the gateway in a straightforward manner. Example An XML RPC request like this: value1 value2 value3 Will result in an method call like this: request_name(param1 = value1, param2 = value2, param3 = value3) XML RPC responses similarly specify the name of the response and have a collection of parameters.
Parameter Type Specification Overview The type of a parameter is specified by the attribute “type” within the tag. Example param1 is specified as being of type string: My favorite color is blue. If no type is specified, the value will be converted to a bool, int or float, in that order. Example TRUE param1 is a bool 1 param1 is an int 1.0 param1 is a float For responses, type will always be specified.
Simple Parameter Types int example: 42 0xFF float example: 3.14159 bool Takes “TRUE” or “FALSE”, case insensitive. example: TRUE string A character string. example: Tis but a scratch. MAC Intended for use with long address strings, which commonly contain delimiter characters.
Complex Parameter Types list A list of subparameters. Note that because a list is an anonymous data structure, the tag names of subparameters are ignored. example: - 42
- FALSE
- Camelot!
would generate: param=[42, False, “Camelot!”] dict A dictionary of subparameters. The tag names of the subparameters will become the keys of the dictionary.
record A record object with specific subparameters. The subparameters will be passed to the record object’s constructor according to tag name. (See “Record Reference” on page 116.) example: 9000 You must bring us... TRUE would generate: param=MagicRecord(foo = 9000, bar = “You must bring us...
Aliases XML RPC requests can be abstracted using aliases. To use an alias which has been defined, use the “alias” type. Alias replacements are performed in place.
The request that needs to be performed has the following structure: value value value Ordinarily a different request would be sent to each gateway, since the thermostat addresses on the two networks are different. However, since a THERMOSTAT alias is defined on each gateway for its local thermostat, the same request can be sent to both.
RPC_request will not be available while a synchronous request is blocking. (For an example using synchronous requests, see RPC Request and Response Example on page 51.
Appendix A XML RPC INTERFACE REFERENCE General Requests/Responses registry_configuration Sets or gets a registry entry. Can only be used to access an existing entry, not to create a new one. registry_configuration Parameters: Parameter Type Description name string Name of the registry entry to access. value (optional) bool, int, float, string or none If provided, this will set registry name to value. If not provided, this will get the value of registry entry in the response.
add_module Adds a module without stopping gateway execution. The module is scanned after it has been added and any interface, endpoint, cluster, or record classes are immediately available for use in other interface commands. The module will also be added to modules.ini so that on startup the module will still be imported. Note: The module’s .py, .pyc or .pyo file must first be uploaded to the gateway before it can be added by this method. A .py file takes significantly more memory then a .pyc or .
add_interface Instantiates an interface of the given class, making all public methods inside that class available to be called via RPC. The interface will also be added to interfaces.ini so that on startup the interface will still be available. add_interface Parameters: Parameter interface_class Type string Description Name of the interface class to be instantiated. add_interface_response Parameters: Parameter interface_class Type string Description Name of the interface class that was instantiated.
add_endpoint Instantiates an endpoint of the given class, along with any of its default clusters. If no endpoint ID is provided, the next available ID will be chosen. Optional parameters will override defaults of the endpoint class. The endpoint will also be added to endpoints.ini so that on startup the endpoint will be instantiated. add_endpoint Parameters: Parameter Type Description endpoint_class string Name of the endpoint class to be instantiated.
remove_endpoint Removes an endpoint with the given endpoint ID which has been previously added from endpoints.ini on startup or via the add_endpoint command. Endpoints added in any other fashion cannot be removed by this command. Also removes the endpoint from endpoints.ini so that it will not be instantiated at startup. Note: Any clusters on the given endpoint will also be removed when the endpoint is removed.
add_cluster_response Parameters: Parameter Type Description endpoint_id int 8-bit identifier of the endpoint to which the cluster was added. cluster_class string 16-bit identifier of the cluster that was added. cluster_id int 16-bit identifier of the cluster. server_or_client int Whether the cluster is a server (0) or client (1) cluster. enable_APS_encryption bool Whether the cluster uses APS encryption or not. remove_cluster Removes a cluster of the given class from the given endpoint.
get_version Returns the version information of the given module. If no module is specified, returns the overall version of the firmware. Each module can be defined with a __version__ and __version_extended__ variable that can be set to any type. (See “Simple Parameter Types” on page 57 and “Complex Parameter Types” on page 58.) This command will return version information for the given module. If no module is given overall firmware version will be retrieved from Version.py.
help_response Parameters: Parameter registry (optional) Type list Description Included only if requested. item - dict - Contains the information about the given registry entry. name - string - Name of the registry entry. value - int, bool, string or none - Current value of the registry entry. description - string - doc string of the registry entry. methods (optional) list Included only if requested. item - dict - Contains the information about the given RPC method. name - string - Name of the method.
exit Terminates the program and associated processes. No parameters. No response. message (response only) This is an unsolicited message sent by the gateway and typically indicates either operational status or errors. Note: Only messages with severity greater than or equal to RPC_General_Interface.debug_rpc_severity will be sent. (See “RPC_General_Interface.debug_rpc_severity” on page 46) message Parameters: Parameter Type Description severity int Severity of the message.
set_time Parameters: Parameter Type Description UTC_1970 (optional) int Set the number of seconds since Jan. 1, 1970, universal coordinate time UTC_2000 (optional) int Set the number of seconds since Jan. 1, 2000, universal coordinate time set_time_response Parameters: Parameter Type Description UTC_1970 int Number of seconds since Jan. 1, 1970, universal coordinate time UTC_2000 int Number of seconds since Jan.
ZigBee Requests/Responses add_device Adds the device to the list of known devices and to devices.ini. Additionally, if the XBee on the gateway is a coordinator and a link key or installation code is provided, the link key for the device will be added to the link key table of the XBee. This will allow the remote device to join the network. An optional join time can be specified which will temporarily enable node joining on the network.
remove_device Parameters: Parameter Type device_address MAC Description 64-bit extended address of the remote device to be removed. remove_device_response Parameters: Parameter Type device_address MAC Description 64-bit extended address of the remote device that was removed. enable_joining Enables node joining on the network for the specified number of seconds. If 0, node joining will immediately be disabled.
get_device_information Parameters: Parameter device_address (optional) Type Description 64-bit address of the device about which to return information. If not provided, the device information for every known device will be returned. MAC get_device_information_response Parameters: Parameter record_list Type Description list Each item in the list corresponds to a device on the network.
bind Parameters: Parameter Type Description destination_address MAC 64-bit extended address of the device to which to send the ZDO bind request destination_endpoint_id int 8-bit identifier of the endpoint on the remote device on which the target cluster exists source_endpoint_id int 8-bit identifier of the endpoint on the local device on which the target cluster exists cluster_id int 16-bit identifier of the cluster to be bound by the bind request bind_request Parameters: Parameter Type Des
unbind_response Parameters: Parameter Type Description status int Indicates the success or failure of the unbind request using standard ZDO status values.
configure_zigbee_network_response Parameters: Parameter Type Description extended_pan_id int Extended PAN ID set on the gateway. channel_mask int 16-bit bitmask of the channels to use for joining or forming a network. Bits 0 - 16 map directly to channels 0x0B - 0x1A. join_interval int Interval between join attempts for router. This parameter will also set the registry_confirmation parameter ZDO_Device_Manager.join_interval.
ZCL Requests/Responses In order to perform a ZCL command on a remote server cluster, a corresponding client cluster must exist locally. In order to perform a ZCL command on a remote client cluster, a corresponding server cluster must exist locally. If necessary, the add_cluster command can be used to create a ZCL cluster of the appropriate type. (See “add_cluster” on page 67) Note: Some local ZCL requests do not have this limitation.
Parameter Type Description manufacturer_code (optional) int 16-bit manufacturer code of the attributes in the record list. record_list List of records which made up the payload of the ZCL Read Attributes Response Command. item - ReadAttributeStatusRecord (See “ReadAttributeStatusRecord” on page 120.) list write_attributes Writes to ZCL attributes on the given cluster on the given device and endpoint. Writes may be normal or undivided.
Parameter Type Description destination_endpoint_id (optional) int 8-bit identifier of the endpoint to which the response was sent. source_address (optional) MAC 64-bit extended address of the device from which the response was sent. manufacturer_code (optional) int 16-bit manufacturer code of the attributes in the record list. record_list List of records which made up the payload of the ZCL Write Attributes Response Command. list item - WriteAttributeResponseRecord.
Parameter Type Description destination_endpoint_id (optional) int 8-bit identifier of the endpoint to which the response was sent. source_address (optional) MAC 64-bit extended address of the device from which the response was sent. manufacturer_code (optional) int 16-bit manufacturer code of the attributes in the record list. record_list list List of records which made up the payload of the ZCL Discover Attributes Response Command. item - AttributeInformationRecord.
start_receiving_reports_response Parameters: Parameter Type Description cluster_id int 16-bit identifier of the target cluster from which the response was sent. server_or_client int Target cluster is a server (0) or client (1) cluster. profile_id int 16-bit profile identifier of the endpoint from which the response was sent. source_endpoint_id int 8-bit identifier of the endpoint from which the response was sent.
Parameter Type Description manufacturer_code (optional) int 16-bit manufacturer code of the attribute in the record. record AttributeReportRecord A single attribute report extracted from the payload of a ZCL Report Attributes Command. (See “AttributeReportRecord” on page 121) stop_receiving_reports Configures the target cluster to stop sending ZCL Report Attributes Commands for the specified attributes to the local device.
Parameter Type Description source_address MAC 64-bit extended address of the device from which the response was sent. manufacturer_code (optional) int 16-bit manufacturer code of the attributes in the record list. record_list list List of records derived from the payload of the ZCL Configure Reporting Response Command.
Parameter Type Description source_endpoint_id int 8-bit identifier of the endpoint from which the response was sent. destination_endpoint_id int 8-bit identifier of the endpoint to which the response was sent. source_address MAC 64-bit extended address of the device from which the response was sent. manufacturer_code (optional) int 16-bit manufacturer code of the attributes in the record list.
Parameter Type Description reporting_direction int Configuration to be read is for reports being sent from (0) or sent to (1) the target cluster. destination_endpoint_id int 8-bit identifier of the endpoint on which the target cluster exists. source_endpoint_id (optional) int 8-bit identifier of the endpoint from which the ZCL command will be sent. destination_address MAC 64-bit extended address of the device hosting the destination endpoint.
identify Instructs the target device to begin self-identification. When the target device is a gateway, it will rapidly blink its associate LED for self-identification. identify Parameters: Parameter Type Description destination_endpoint_id int 8-bit identifier of an endpoint hosting the Identify server cluster (0x0003). source_endpoint_id (optional) int 8-bit identifier of the endpoint from which the ZCL request will be sent. Required for remote requests.
send_ZCL Parameters: Parameter Type Description cluster_id int 16-bit identifier of the target cluster to which the request will be sent. server_or_client int Target cluster is a server (0) or client (1) cluster. destination_endpoint_id int 8-bit identifier of the endpoint on which the target cluster exists. source_endpoint_id int 8-bit identifier of the endpoint from which the ZCL request will be sent.
send_ZCL_response Parameters: Parameter Type Description cluster_id int 16-bit identifier of the cluster from which the response was sent. server_or_client int Target cluster from which the response was sent is a server (0) or client (1) cluster. profile_id int 16-bit profile identifier of the endpoint from which the response was sent. source_endpoint_id int 8-bit identifier of the endpoint from which the response was sent.
SE Requests/Responses Demand Response / Load Control (DRLC) Commands - Common get_DRLC_events Returns the gateway’s list of valid DRLC events. This command can be used on a DRLC server or client cluster. get_DRLC_events Parameters: Parameter Type Description endpoint_id (optional) int 8-bit identifier of the endpoint on the gateway hosting the DRLC cluster. Defaults to the standard SE endpoint (0x5E). server_or_client (optional) int Return events from local server (0) or client (1) cluster.
create_DRLC_event Parameters: Parameter Type Description source_endpoint_id (optional) int 8-bit identifier of the endpoint on the gateway hosting the DRLC server cluster. Defaults to the standard SE endpoint (0x5E). record LoadControlEventRecord Contains information about the event to add. (See “LoadControlEventRecord” on page 125).
cancel_DRLC_event Parameters: Parameter Type Description source_endpoint_id (optional) int 8-bit identifier of the endpoint on the gateway hosting the DRLC server cluster. Defaults to the standard SE endpoint (0x5E). record CancelLoadControlEventRecord Contains information about the cancel.
cancel_all_DRLC_events Removes all DRLC events from the gateway’s list of events. A DRLC Cancel All Load Control Events command (0x02) will be immediately sent to all client clusters hosted on an active device. This command will be sent from the specified endpoint hosting a DRLC server cluster on the local device. cancel_all_DRLC_events Parameters: Parameter Type Description source_endpoint_id (optional) int 8-bit identifier of the endpoint on the gateway hosting the DRLC server cluster.
received_report_event_status Parameters: Parameter Type Description source_address MAC 64-bit extended address of the device hosting the DRLC client. source_endpoint_id int 8-bit identifier of the endpoint on the remote device hosting the DRLC client. record ReportEventStatusRecord Describes the status of the event. (See “ReportEventStatusRecord” on page 126) cluster_id int 16-bit identifier of the DRLC cluster.
Parameter Type Description record (optional) GetScheduledEventsRecord Returns the start time and number of events requested from the DRLC server cluster. Only included in the response if record was included in the original request. (See “GetScheduledEventsRecord” on page 127.) device_list list List of all devices to which the message was sent. Will be empty if status is not success (0x00). item - MAC - 64-bit extended address of a device to which the cancel was sent.
received_DRLC_event (response only) This RPC response message is generated when a DRLC client cluster hosted on the local device received a Load Control Event command (0x00). The event will be added to the DRLC client. received_DRLC_event Parameters: Parameter Type Description status int Indicates the success or failure of receiving the DRLC event. Can be success (0x00), invalid field (0x85), or duplicate exists (0x8A).
Parameter Type Description cluster_id int 16-bit identifier of the DRLC cluster. record CancelLoadControlEventRecord Contains information about the received event. (See “CancelLoadControlEventRecord” on page 126.) received_DRLC_cancel_all_events (response only) This RPC response message is generated when a DRLC client cluster hosted on the local device received a Cancel All Load Control Events command (0x02).
updated_active_DRLC_events (response only) The DRLC client cluster keeps a list of currently active DRLC events. When this list changes, the client generates an updated_active_DRLC_events. This can occur when an event starts, stops, or is canceled. An empty list of events will be returned when there are no active events. updated_active_DRLC_events Parameters: Parameter Type Description destination_endpoint_id int 8-bit identifier of the endpoint on the gateway that hosts the DRLC client cluster.
Messaging Commands - Common get_message_events Returns the gateway’s list of valid message events. This command can be used on a message server or client cluster. get_message_events Parameters: Parameter endpoint_id (optional) Type Description int 8-bit identifier of the endpoint on the gateway hosting the Messaging cluster. Defaults to the standard SE endpoint (0x5E).
create_message_event Parameters: Parameter Type Description source_endpoint_id (optional) int 8-bit identifier of the endpoint on the gateway hosting the Messaging server cluster. Defaults to the standard SE endpoint (0x5E). record DisplayMessageRecord Contains information about the event to add. (See “DisplayMessageRecord” on page 127).
cancel_message_event_response Parameters: Parameter Type Description source_endpoint_id int 8-bit identifier of the endpoint on the gateway hosting the Messaging server cluster. cluster_id int 16-bit identifier of the cluster to which the Messaging command was sent status int Indicates the local success or failure of cancelling the event using standard ZCL status values. A cancel should never fail locally so this field should always contain success (0x00).
cancel_all_message_events_response Parameters: Parameter Type Description source_endpoint_id int 8-bit identifier of the endpoint on the gatway hosting the Messaging server cluster. cluster_id int 16-bit identifier of the cluster to which the Messaging command was sent. status int Indicates the local success or failure of cancelling the events using standard ZCL status values. A cancel should never fail locally so this field should always contain success (0x00).
received_message_event (response only) This RPC response message is generated when a Messaging client cluster hosted on the local device receives a Display Message command (0x00). received_message_event Parameters: Parameter Type Description status int Indicates the success or failure of receiving the message event. Can be success (0x00), invalid field (0x85), or duplicate exists (0x8A). source_address MAC 64-bit extended address of the device hosting the Messaging server cluster.
Parameter Type Description cluster_id int 16-bit identifier of the cluster to which the message command was sent. record CancelMessageEventRecord Contains information about the received event. (See “CancelMessageEventRecord” on page 128.) updated_active_message_events (response only) The messaging client cluster keeps a list of currently active message events. When this list changes, the client generates an updated_active_message_events response.
get_last_message_event_response Parameters: Parameter Type Description status int Indicates the success or failure of requesting the last event using ZCL status values. Can be success (0x00), invalid field (0x85), or not found (0x8B). source_endpoint_id int 8-bit identifier of the endpoint on the gateway hosting the Messaging client cluster. cluster_id int 16-bit identifier of the cluster from which the message command was sent.
Parameter Type Description cluster_id int 16-bit identifier of the cluster from which the message command was sent. record (optional) MessageConfirmationRecord Specified the message ID for the message event or cancel message event being confirmed. Only include if record is specified in the original confirm_message command (See “MessageConfirmationRecord” on page 129.) device_list list List of all devices to which the confirmation was sent. Will be empty if status is not success (0x00).
Price Commands - Common get_price_events Returns the gateway’s list of valid price events. This command can be used on a price server or client cluster. get_price_events Parameters: Parameter Type Description endpoint_id (optional) int 8-bit identifier of the endpoint on the gateway hosting the Price server cluster. Defaults to the standard SE endpoint (0x5E). server_or_client int Return events from local server (0) or client (1) cluster. If not specified, will search endpoint for Price cluster.
create_price_event Parameters: Parameter Type Description source_endpoint_id (optional) int 8-bit identifier of the endpoint on the gateway hosting the Price server cluster. Defaults to the standard SE endpoint (0x5E). record PublishPriceRecord Contains information about the event to be added. (See “PublishPriceRecord” on page 128).
cancel_all_price_events_response Parameters: Parameter Type Description source_endpoint_id int 8-bit identifier of the endpoint on the gateway hosting the Price server cluster. status int Indicates the local success or failure of cancelling all events using standard ZCL status values. A cancel should never fail locally, so this field should always contain success (0x00).
Price Commands - Client get_current_price_event Get server to resend the current price event. Client sends a Get Current Price Event command (0x00) to each of the active price servers. get_current_price_event Parameters: Parameter source_endpoint_id (optional) Type int Description 8-bit identifier of the endpoint on the gateway hosting the Price client cluster. Defaults to the standard SE endpoint (0x5E).
get_scheduled_price_events Get server to resend scheduled price events. Client sends a Get Scheduled Price Events command (0x01) to each of the active Price servers. This request can specify a start time and maximum number of events for the server to send. get_scheduled_price_events Parameters: Parameter Type Description source_endpoint_id (optional) int 8-bit identifier of the endpoint on the gateway hosting the DRLC client cluster. Defaults to the standard SE endpoint (0x5E).
clear_price_events_response Parameters: Parameter Type Description source_endpoint_id int 8-bit identifier of the endpoint on the gateway hosting the Price client cluster. cluster_id int 16-bit identifier of the Price cluster. received_price_event (response only) This RPC response message is generated when a Price cluster hosted on the local device receives a Publish Price Event command (0x00). The event will be added to the Price client.
Aliasing Commands Adding, removing and listing aliases are all standard RPC requests (see below). The use of an alias does not follow the RPC format because they can be included anywhere within an RPC request or represent one or more RPC requests. To insert an alias into an RPC request, use the alias name as the tag name and set the type to “alias”. The Python RPC manager will replace the alias with the XML from the add_alias command. See “Aliases” on page 60 for more information.
remove_alias Parameters: Field alias_name Type none Description Tag is the name of the alias to be removed. remove_alias_response Parameters: Parameter alias_name Type bool Description Tag is the name of the alias that was removed. Set to TRUE if alias was removed. Set to FALSE if alias didn’t exist. list_aliases Lists all aliases that are currently defined. This command takes no parameters.
RECORD REFERENCE Records are used on the gateway both internally and as input and output parameters in the RPC Interface. Many of the records correspond to descriptions found in the ZigBee, ZCL, or SE specifications and where appropriate this has been noted. Type, descriptions, defaults, etc for record fields are specific to their use in the RPC Interface. See the appropriate specification for more detailed information.
Parameter Type Description node_type (optional) int Identifier of the node type of the device. Included if the device has responded to a ZDO Node_Desc_req. manufacturer_id (optional) int Manufacturer identifier of the device. Included if the device has responded to a ZDO Node_Desc_req. Node_Desc_rsp All parameters following nwk_addr correspond to the Node Descriptor, whose format is given in the ZigBee Specification. If status is not success (0) then all parameters following nwk_addr are excluded.
Power_Desc_rsp All parameters following nwk_addr correspond to the Power Descriptor, whose format is given in the ZigBee Specification. If status is not success (0) then all parameters following nwk_addr are excluded. Parameter Type Description status int On failure this parameter will be non-zero and the descriptor is not present in the response. nwk_addr int 16-bit short network address of the device.
ZCL Records ReadAttributeRecord Corresponds to Read Attributes parameters as given in the ZCL Specification.. Parameter Type attribute_id int Description Identifier of the attribute that is to be read. ReadAttributeStatusRecord Corresponds to Read attribute status record as documented for Read Attributes Response in the ZCL Specification. Parameter Type Description status int On failure this parameter will be non-zero and the attribute_type and value are not present in the response.
WriteAttributeResponseRecord Corresponds to Write attribute status record as documented for Write Attributes Response in the ZCL Specification Parameter Type Description status int On failure this parameter will be non-zero. attribute_id int Identifier of the attribute that was written. attribute_type int Copied from the original request parameter. value depends on the attribute type Copied from the original request parameter.
AttributeReportingConfigurationResponseRecord Corresponds to Attribute status record as documented for Configure Reporting Response in the ZCL Specification. Parameters other than status and attribute_id are copied from the original request parameters. If status is not success (0) then all other parameters except attribute_id are excluded. Parameter Type Description status int On failure this parameter will be non-zero and only attribute_id is included in the response.
StopReportingRecord When passed as a parameter to the stop_receiving_reports RPC request this record is used to generate an AttributeReportingConfigurationRecord suitable for stopping reports. Parameter attribute_id Type int Description Identifier of the attribute for which reporting will be stopped. StopReportingStatusRecord A parameter of the stop_receiving_reports_response RPC response. Parameter Type Description status int If success (0) then reporting successfully stopped.
Parameter Type Description direction int If 0x00, then configuration is for transmitting reports. If 0x01, then configuration is for receiving reports. Defaults to 0x00. attribute_type int Include if configuration is for transmitting reports. Defaults to Unknown (0xFF). min_interval int Include if configuration is for transmitting reports. Defaults to 0. max_interval int Included if configuration is for transmitting reports. Defaults to 0.
LocalReportingConfigurationRecord Corresponds to the information stored locally for reporting. This report includes addressing information for the remote device and the reporting configuration.
SE Records Demand Response / Load Control (DRLC) LoadControlEventRecord Corresponds to payload of Load Control Event in the SE Specification. Parameter Type Description issuer_event_id int No default. device_class int Defaults to 0x0FFF (all non-reserved device classes). utility_enrollment_group int Defaults to 0x0 (all groups). start_time int Defaults to 0x0 (now). duration_in_minutes int No default. criticality_level int Defaults to 0x1 (lowest non-reserved priority).
CancelAllLoadControlEventsRecord Corresponds to payload of Cancel All Load Control Events in the SE Specification. Parameter cancel_control Type int Description Defaults to 0x1 (use randomization from original event). ReportEventStatusRecord Corresponds to payload of Report Event Status in the SE Specification. Parameter Type Description issuer_event_id int No default. event_status int No default. event_status_time int Defaults to current time when record is created.
Messaging DisplayMessageRecord Corresponds to payload of Display Message in the SE Specification. Parameter Type Description message_id int No default.
MessageConfirmationRecord Corresponds to payload of Message Confirmation in the SE Specification. Parameter Type Description message_id int No default. confirmation_time int Defaults to current time when record is created. GetScheduledEventsRecord Corresponds to payload of Get Scheduled Events in the SE Specification.
Parameter Type Description price_ratio int Defaults to 0xFF (denotes not used). generation_price int Defaults to 0xFFFFFFFF (denotes not used). generation_price_ratio int Defaults to 0xFF (denotes not used). alternate_cost_deliverd int Defaults to 0xFFFFFFFF (denotes not used). alternate_cost_unit int Defaults to 0x1 (kg of CO2 per unit measure). alternate_cost_trailing_digit int Defaults to 0xFF.
Appendix B SMART ENERGY CERTIFICATE MANAGEMENT All devices that operate in a ZigBee Smart Energy network must have a certificate installed that authenticates the device and allows it to securely join and communicate on the network. A certificate must be issued by the certificate authority (CA). Each certificate is tied to the 64-bit extended address of the device. Currently there are two types of certificates issued by the CA. Production certificates are intended for use in deployed Smart Energy networks.
Obtaining Test Certificates Certicom is the only recognized CA for ZigBee Smart Energy. Certicom provides an online form to request test certificates at http://www.certicom.com/index.php/ gencertregister. Certificates are linked to a specific 64-bit extended address (EUI) which must be provided to Certicom. Before requesting test certificates determine the EUI of all devices which will need test certificates.
Installing Certificates Certificates obtained from Certicom should have the following format where ######## will be a long hexadecimal number for each entry. CA Public Key: ######## Device Implicit Cert: ######## Device Private Key: ######## Device Public Key: ######## To install certificates onto either the ConnectPort X2 for Smart Energy or a standalone XBee an AT command must be sent to configure the CA Public KEY (ZU), Device Implicit Cert (ZT), and Device Private Key (ZV).
4. Write settings to non-volatile flash WR 5. Reset network NR Installing Certificates on a Standalone XBee Module The easiest method to install a certificate on a Standalone XBee Module is using the InPremise Display/Meter Simulator sample on page 30. If this is not possible X-CTU may also be used to send the necessary AT commands.
