Digi ConnectPort X2 Manual de usuario

ConnectPort X2for Smart EnergyUser’s Manual90001120_FSE_Framework version 1.3.0.

3ZIGBEESMARTENERGYDescriptionThe ZigBee Smart Energy Profile defines a wireless home area network (HAN) to manage energy in residential areas. These

91SE Requests/ResponsesDemand Response / Load Control (DRLC) Commands - Commonget_DRLC_eventsReturns the gateway’s list of valid DRLC events. This co

Parameter Type Descriptionsource_endpoint_id (optional)int 8-bit identifier of the endpoint on the gateway hosting the DRLC server cluster. Defaults

Parameter Type Descriptionsource_endpoint_id (optional)int 8-bit identifier of the endpoint on the gateway host-ing the DRLC server cluster. Defaults

94cancel_all_DRLC_eventsRemoves all DRLC events from the gateway’s list of events. A DRLC Cancel All Load Control Events command (0x02) will be immedi

Parameter Type Descriptionsource_address MAC 64-bit extended address of the device hosting the DRLC client.source_endpoint_id int 8-bit identifier of

96clear_DRLC_eventsRemoves all DRLC events from the gateway’s DRLC client cluster’s list of events. Events are still active on the server and may be r

97received_DRLC_event (response only)This RPC response message is generated when a DRLC client cluster hosted on the local device received a Load Cont

98received_DRLC_cancel_all_events (response only)This RPC response message is generated when a DRLC client cluster hosted on the local device received

99updated_active_DRLC_events (response only)The DRLC client cluster keeps a list of currently active DRLC events. When this list changes, the client

100Messaging Commands - Commonget_message_eventsReturns the gateway’s list of valid message events. This command can be used on a message server or c

4CONNECTPORTX2FORSMARTENERGYDescriptionThe Digi ConnectPort X2 for Smart Energy is a gateway on a Smart Energy network that provides secure access

Parameter Type Descriptionsource_endpoint_id (optional)int 8-bit identifier of the endpoint on the gateway hosting the Messaging server cluster. Def

Parameter Type Descriptionsource_endpoint_id int 8-bit identifier of the endpoint on the gateway hosting the Messaging server cluster. cluster_id int

Parameter Type Descriptionsource_endpoint_id int 8-bit identifier of the endpoint on the gatway hosting the Messaging server cluster. cluster_id int

104received_message_event (response only)This RPC response message is generated when a Messaging client cluster hosted on the local device receives a

105updated_active_message_events (response only)The messaging client cluster keeps a list of currently active message events. When this list changes,

Parameter Type Descriptionstatus int Indicates the success or failure of requesting the last event using ZCL status values. Can be success (0x00), i

107clear_message_eventsRemoves all message events from the gateway’s Messaging client cluster’s list of events. Events are still active on the server

108Price Commands - Commonget_price_eventsReturns the gateway’s list of valid price events. This command can be used on a price server or client clust

Parameter Type Descriptionsource_endpoint_id (optional)int 8-bit identifier of the endpoint on the gateway hosting the Price server cluster. Defaults

Parameter Type Descriptionsource_endpoint_id int 8-bit identifier of the endpoint on the gateway hosting the Price server cluster.status int Indicate

5during 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.• Mes

111Price Commands - Clientget_current_price_eventGet server to resend the current price event. Client sends a Get Current Price Event command (0x00)

112get_scheduled_price_eventsGet server to resend scheduled price events. Client sends a Get Scheduled Price Events command (0x01) to each of the act

Parameter Type Descriptionsource_endpoint_id int 8-bit identifier of the endpoint on the gateway hosting the Price client cluster.cluster_id int 16-b

114Aliasing CommandsAdding, removing and listing aliases are all standard RPC requests (see below). The use of an alias does not follow the RPC forma

115<remove_alias> <alias_name/></remove_alias>Field Type Descriptionalias_name none Tag is the name of the alias to be removed.Par

116RECORDREFERENCERecords are used on the gateway both internally and as input and output parameters in the RPC Interface. Many of the records corres

117Node_Desc_rspAll parameters following nwk_addr correspond to the Node Descriptor, whose format is given in the ZigBee Specification.If status is no

118Power_Desc_rspAll parameters following nwk_addr correspond to the Power Descriptor, whose format is given in the ZigBee Specification.If status is

119ZCL RecordsReadAttributeRecordCorresponds to Read Attributes parameters as given in the ZCL Specification.Parameter Type Descriptionattribute_id i

120WriteAttributeResponseRecordCorresponds to Write attribute status record as documented for Write Attributes Response in the ZCL SpecificationParame

6Network DiagramThis diagram shows the role of a Gateway within an Advanced Metering Infrastructure (AMI) network.

121AttributeReportingConfigurationResponseRecordCorresponds to Attribute status record as documented for Configure Reporting Response in the ZCL Speci

122StopReportingRecordWhen passed as a parameter to the stop_receiving_reports RPC request this record is used to generate an AttributeReportingConfig

123AttributeInformationRecordCorresponds to Attribute information as documented for Discover Attributes Response in the ZCL Specification.Parameter T

124LocalReportingConfigurationRecordCorresponds to the information stored locally for reporting. This report includes addressing information for the

125SE RecordsDemand Response / Load Control (DRLC)LoadControlEventRecordCorresponds to payload of Load Control Event in the SE Specification.Parameter

126CancelAllLoadControlEventsRecordCorresponds to payload of Cancel All Load Control Events in the SE Specification.Parameter Type Descriptioncancel_

127MessagingDisplayMessageRecordCorresponds to payload of Display Message in the SE Specification.Parameter Type Descriptionmessage_id int No defaul

128MessageConfirmationRecordCorresponds to payload of Message Confirmation in the SE Specification.Parameter Type Descriptionmessage_id int No defaul

129GetScheduledPricesRecordCorresponds to payload of Get Scheduled Prices in the SE Specification.Parameter Type Descriptionstart_time int Defaults t

131Appendix BSMARTENERGYCERTIFICATEMANAGEMENTAll devices that operate in a ZigBee Smart Energy network must have a certificate installed that authe

7RESOURCESThe following resources are referred to throughout this User’s Manual. This page is intended to be a convenient reference. The following dow

132Obtaining Test CertificatesCerticom is the only recognized CA for ZigBee Smart Energy. Certicom provides an online form to request test certificate

133Installing CertificatesCertificates obtained from Certicom should have the following format where ######## will be a long hexadecimal number for ea

1344. Write settings to non-volatile flash<xbee_AT> <command type="string">WR</command></xbee_AT>5. Reset network&l

8• ZigBee Smart Energy Profile Specification, ZigBee Document 075356r15.

9Upon completion of the Getting Started section you will be able to:• Create an account on iDigi.com• Configure your gateway• Connect your gateway to

10PRODUCTCOMPONENTS,REQUIREMENTS,ANDRESOURCESProduct ComponentsPC RequirementYou will also need: A personal computer,connected to the Internet.

11Additional ProductsTo run the In-Premise Display/Meter Simulator sample (see page 30), you will also need one of the following devices that has been

12SETUPIDIGIANDGATEWAYIntroduction to iDigiThe iDigi Platform is a network management solution that provides easy integration for M2M (Machine-to-

©Digi International Inc. 2010. All Rights Reserved.The Digi logo is a registered trademarks of Digi International, Inc.Digi Connect, Connectware Manag

13Create an Account on iDigi.comTo get started, set up an account on the iDigi Platform as follows.1. Navigate to http://www.idigi.com.2. Click on the

143. 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, cli

15Configure the GatewayConnect and Power on the ConnectPort X2 1. Unpack the ConnectPort X2 for Smart Energy gateway.2. Connect the power supply to th

165 Python thread6

172. In the Devices list, click the button to bring up the Add Devices dialog.

183. 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, ch

196. Your device information will load into a separate tab.

20ADD DEVICESTOTHEZIGBEESENETWORKThe Google App sample may be used to send RPC requests to the gateway. (See “iDigi SE Web Sample, Communicating

21Add Device to Trust Center GatewayIn order to add a device to the Smart Energy network with the X2 gateway running as a trust center (ESI coordinato

22All of the parameters are optional. The response will give the current value for everything but the link key and the installation code. Once a rou

iOverview ... 1ZigBee Smart Energy ...

23<get_device_information_response timestamp="1257799818.0"> <record_list type="list">This is our local device

24 <active_endpoints type="list"> <item>0x5E</item> </active_endpoints>

25IDIGISEWEBSAMPLE,COMMUNICATINGWITHGATEWAYOverviewThis sample provides a simple demonstration of a system which communicates with a ConnectPort

263. On the Options window, select the device ID of your gateway and click Save.

274. 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 initializa

285. Query the gateway for available commands by clicking the Refresh Command List button. This will populate the command list.

296. Select a command from the list and modify parameters as necessary. Click Execute.

30XML requests and responses will appear in the output window and can be expanded by clicking on them.

31INPREMISEDISPLAY/METERSIMULATORSAMPLEOverviewThis sample simulates the basic functionality of a Smart Energy In-Premise Display or Meter with an

325. 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 commonl

iiIn-Premise Display ...35Meter ...

336. Load the test certificate information that corresponds to the serially-attached XBee. This can be accomplished in two ways: Load Cert From Filea.

34Manual Entrya. Manually enter the CA Public Key, Implicit Cert and Private Key.7. Write the Certificate to the serially-attached XBee by clicking Wr

359. 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 RP

36Network ViewThe Network tab provides a convenient overview of all endpoints and clusters of devices which have been detected on the network. The inf

37ZCL attributes can be read and written from the Network Tab after selecting an attribute.In-Premise DisplayTo create an In-Premise Display endpoint,

38</create_price_event>The price event will automatically be sent to all known Price client clusters. You should see the new price value appear.

39</create_message_event>The message event will automatically be sent to all known Messaging client clusters. You should see the new message app

40Additionally, if a Simple Metering server cluster is found on the network, the current usage information will be automatically retrieved and display

41MeterTo create a Metering Device endpoint, go to the Meter tab and click the Enable Meter check box. This will create a Simple Metering server clust

40The following section describes the standard initialization, automation, and configuration features of the gateway.General OperationC HAPTER 2

iiiremove_interface...65add_endpoint...

41STA R TU P SEQUENCEThe following operations are performed in order by the gateway when powered on.1. Core modules are imported and core objects are

42REMOTEDEVICEMANAGEMENTDevice DetectionA remote device is detected when one of the following happens:• A ZigBee message is received by the gateway

43Transmission Retries and Device InactivityA remote device is considered inactive if a certain number of sequential transmissions to that device fail

44ZCL Reporting and Device ActivityIf ZCL attribute reporting is configured on the gateway to expect reports from an active remote device, and that de

45REGISTRYThe registry is created when the gateway first boots and contains power-safe global settings to control gateway behavior. Individual entries

46RPC_General_Interface.debug_rpc_severity 1 If a message is generated by the firmware with severity greater than or equal to this value, it will be s

47ZDO_Device_Manager.require_explicit_device_add FALSE If TRUE, devices must be explic-itly added before they can become active. If FALSE, devices can

48POWERSAFETYCertain information is automatically saved to flash in order to maintain gateway functionality in case of a power failure.Global Saved F

49Hidden Saved Files Aliases and certain cluster specific information are stored in subdirectories under /WEB/python/. These files are not accessible

50The following section explains the basics of communicating with the gateway when it is running the SE framework. An API reference for all RPC reques

ivupdated_active_DRLC_events (response only)...99get_message_events ...100create_message

51RPC Request and Response ExampleRPC requests and responses are contained in an RCI wrapper, which specifies the command target (i.e. “RPC_request”).

52The responses from multiple devices will be accumulated into a single SCI response by iDigi. The reply to the above example would look like the foll

53The reply to an RPC_response request contains a listing of RPC responses in chronological order. By default timestamps are enabled and every respons

54Automatic Response PushingThe gateway can be configured to push responses immediately to the iDigi server instead of the default polling mode via RP

55XMLRPCINTERFACEOVERVIEWConversion to Method CallXML RPC requests convert into method calls on the gateway in a straightforward manner. ExampleA

56Parameter Type Specification OverviewThe type of a parameter is specified by the attribute “type” within the tag.Exampleparam1 is specified as bei

intexample: <param type=”int”>42</param><param type="int">0xFF</param>floatexample: <param type=”float”>3.1415

58Complex Parameter Typeslist A list of subparameters. Note that because a list is an anonymous data structure, the tag names of subparameters are ign

59record A record object with specific subparameters. The subparameters will be passed to the record object’s constructor according to tag name. (See

60AliasesXML RPC requests can be abstracted using aliases. To use an alias which has been defined, use the “alias” type. Alias replacements are perfor

vCancelLoadControlEventRecord...126CancelAllLoadControlEventsRecord ...127ReportEventStatu

61Ordinarily a different request would be sent to each gateway, since the thermostat addresses on the two networks are different. However, since a THE

62RPC_request will not be available while a synchronous request is blocking. (For an example using synchronous requests, see RPC Request and Response

63XMLRPCINTERFACEREFERENCEGeneral Requests/Responsesregistry_configurationSets or gets a registry entry. Can only be used to access an existing ent

64add_moduleAdds a module without stopping gateway execution. The module is scanned after it has been added and any interface, endpoint, cluster, or r

65add_interfaceInstantiates an interface of the given class, making all public methods inside that class available to be called via RPC. The interface

66add_endpointInstantiates an endpoint of the given class, along with any of its default clusters. If no endpoint ID is provided, the next available I

67remove_endpointRemoves an endpoint with the given endpoint ID which has been previously added from endpoints.ini on startup or via the add_endpoint

Parameter Type Descriptionendpoint_id int 8-bit identifier of the endpoint to which the cluster was added.cluster_class string 16-bit identifier of t

69get_versionReturns the version information of the given module. If no module is specified, returns the overall version of the firmware. Each module

Parameter Type Descriptionregistry (optional)list Included only if requested.item - dict - Contains the information about the given registry entry.na

1OverviewCONTENTSThis document provides an introduction to Digi's Smart Energy Framework and explains how to use the framework to set up a Connec

71exitTerminates the program and associated processes. No parameters. No response.message (response only)This is an unsolicited message sent by the ga

Parameter Type DescriptionUTC_1970 (optional) int Set the number of seconds since Jan. 1, 1970, universal coordinate timeUTC_2000 (optional) int Set

73ZigBee Requests/Responsesadd_deviceAdds the device to the list of known devices and to devices.ini. Additionally, if the XBee on the gateway is a co

Parameter Type Descriptiondevice_address MAC 64-bit extended address of the remote device to be removed.Parameter Type Descriptiondevice_address MAC

Parameter Type Descriptiondevice_address (optional)MAC 64-bit address of the device about which to return information. If not provided, the device

Parameter Type Descriptiondestination_address MAC 64-bit extended address of the device to which to send the ZDO bind requestdestination_endpoint_id

Parameter Type Descriptionstatus int Indicates the success or failure of the unbind request using standard ZDO status values. Can be success (0x00),

Parameter Type Descriptionextended_pan_id int Extended PAN ID set on the gateway.channel_mask int 16-bit bitmask of the channels to use for joining o

79ZCL Requests/ResponsesIn order to perform a ZCL command on a remote server cluster, a corresponding client cluster must exist locally. In order to p

80write_attributesWrites to ZCL attributes on the given cluster on the given device and endpoint. Writes may be normal or undivided. If any attribute

2QUESTIONS?For technical assistance with your Drop-in Network, call:1-800-903-8430 (US Only)Country Toll Free NumberArgentina 00-800-3444-3666Australi

81discover_attributesDiscovers all ZCL attributes on the target cluster.Parameter Type Descriptioncluster_id int 16-bit identifier of the target clus

82start_receiving_reportsConfigures the target cluster to begin sending ZCL Report Attributes Commands for the specified attributes to the local devic

Parameter Type Descriptioncluster_id int 16-bit identifier of the target cluster from which the response was sent.server_or_client int Target cluster

84stop_receiving_reportsConfigures the target cluster to stop sending ZCL Report Attributes Commands for the specified attributes to the local device.

85stop_sending_reportsConfigures the local device to stop sending specified ZCL Report Attributes Commands to the destination device. Also sets the de

86get_local_reporting_configurationsReturns all of the reporting configurations of the gateway. This includes configurations for gateway reporting to

87read_reporting_configuration_response Parameters:reporting_direction int Configuration to be read is for reports being sent from (0) or sent to (1)

88identifyInstructs the target device to begin self-identification. When the target device is a gateway, it will rapidly blink its associate LED for s

Parameter Type Descriptioncluster_id int 16-bit identifier of the target cluster to which the request will be sent.server_or_client int Target cluste

Parameter Type Descriptioncluster_id int 16-bit identifier of the cluster from which the response was sent.server_or_client int Target cluster from w