November, 2011 Draft ZigBee-11167

1

Project ZigBee Alliance and HomePlug Powerline Alliance liaison

Title Smart Energy Profile 2.0 Public Application Protocol Specification

Date 3, November, 2011 Submitted

Re: Smart Energy Profile 2.0 Application Protocol Specification

Abstract This document describes the application protocol for the Smart Energy Profile 2.0 release.

Purpose The purpose of this document is to define the messages exchanged between devices that implement the Smart Energy Profile, thereby delivering on the requirements in the SEP 2.0 MRD and TRD, and enabling an interoperable eco-system of Smart Energy devices.

Notice This document has been prepared to assist the ZigBee Alliance and the HomePlug Powerline Alliance. It is offered as a basis for discussion and is not binding on the contributing individual(s) or organization(s). The material in this document is subject to change in form and content after further study. The contributor(s) reserve(s) the right to add, amend or withdraw material contained herein.

Release The contributor acknowledges and accepts that this contribution will be posted in the member area of the ZigBee and HomePlug web sites. Copyright 2011 © ZigBee Alliance, Inc. and HomePlug Powerline Alliance, Inc. All rights Legal Reserved. This information within this document is the property of the ZigBee Alliance and the Notice HomePlug Powerline Alliance and its use and disclosure are restricted.

Elements of ZigBee Alliance and HomePlug Powerline Alliance specifications may be subject to third party intellectual property rights, including without limitation, patent, copyright or trademark rights (such a third party MAY or MAY NOT be a member of ZigBee and/or HomePlug). ZigBee and HomePlug are not responsible and SHALL NOT be held responsible in any manner for identifying or failing to identify any or all such third party intellectual property rights.

This document and the information contained herein are provided on an “AS IS” basis and ZigBee and HomePlug DISCLAIM ALL WARRANTIES EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO (A) ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OF THIRD PARTIES (INCLUDING WITHOUT LIMITATION ANY INTELLECTUAL PROPERTY RIGHTS INCLUDING PATENT, COPYRIGHT OR TRADEMARK RIGHTS) OR (B) ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NON-

Smart Energy Profile 2.0 Page 1 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

INFRINGEMENT. IN NO EVENT WILL ZIGBEE OR HOMEPLUG BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF BUSINESS, OR FOR ANY OTHER DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTIAL, PUNITIVE OR CONSEQUENTIAL DAMAGES OF ANY KIND, IN CONTRACT OR IN TORT, IN CONNECTION WITH THIS DOCUMENT OR THE INFORMATION CONTAINED HEREIN, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. All Company, brand and product names may be trademarks that are the sole property of their respective owners.

The above notice and this paragraph MUST be included on all copies of this document that are made.

ZigBee Alliance, Inc. HomePlug Powerline Alliance, Inc. 2400 Camino Ramon, Suite 375 5200 SW Macadam Ave., Suite 470 San Ramon, CA 94583 Portland, OR 97239

Smart Energy Profile 2.0 Page 2 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2 Foreword 3 The empowerment of consumers to manage their usage and generation of energy is a critical feature of 4 the Smart Grid and is a basis of innovation for new products and services in energy management. To 5 enable this capability, information flow between devices such as meters, smart appliances, plug-in electric 6 vehicles, energy management systems, and distributed energy resources (including renewable energy and 7 storage elements) MUST occur in an open, standardized, and interoperable fashion. The draft 8 specification you are now holding is intended to fulfill those needs. 9 The development of this draft document has been driven by, and seeks to address the requirements of, 10 many activities across the globe. Of note are the efforts within the United States by the National Institute 11 of Standards and Technology (NIST) and the Smart Grid Interoperability Panel (SGIP) (in particular, 12 Priority Action Plans 3, 9, 10, and 11, with influence from many of the others) in fulfillment of the EISA 13 2007 legislation, the European Mandate on Smart Metering (M/441) (in particular, efforts within 14 CEN/CENELEC and ETSI, and the Smart Meter Working Group), as well as similar efforts in Australia, 15 the United Kingdom, Japan, and China, to name only a few. 16 Readers should note that this document is a draft and that suggestions are welcomed. This specification is 17 intended to meet the requirements set forth in the previously published draft Technical Requirements 18 Document (TRD) and will be updated in the future to reflect the ongoing changes to the TRD based on 19 internal review and public comment. This level of development parallelism is meant to speed the 20 progress of this effort, while also providing potential stakeholders who have not had the opportunity to be 21 actively involved with ZigBee Smart Energy a way to comment on the draft documents. 22 This draft document is also intended to enable communications that are link layer agnostic and run over 23 the Internet Protocol (specifically IPv6). Careful consideration was given to premises networks with 24 various architectures, numbers of devices, and constraints while maintaining flexibility, extensibility, and 25 security. 26

Smart Energy Profile 2.0 Page 3 Draft Application Protocol Specification September, 2011 Draft ZigBee-11167

27 Table of Contents 28 1 Introduction ...... 11 29 1.1 Purpose...... 11 30 1.2 Scope ...... 11 31 1.3 Context Overview ...... 11 32 1.4 Document Organization ...... 11 33 1.5 Requirement Language ...... 12 34 1.6 Typography Conventions Used ...... 12 35 1.7 Design Principles ...... 13 36 2 Acknowledgements ...... 14 37 3 Document Revision History ...... 15 38 4 References ...... 16 39 4.1 Smart Energy 2.0 Documents ...... 16 40 4.2 HomePlug Powerline Alliance Documents...... 16 41 4.3 ZigBee Alliance Documents ...... 16 42 4.4 IEC Documents ...... 17 43 4.5 IETF Documents ...... 18 44 4.6 Other References ...... 18 45 4.7 UCA References ...... 19 46 5 Definitions, Acronyms and Abbreviations ...... 20 47 5.1 Acronyms and Abbreviations...... 20 48 5.2 Definitions ...... 20 49 6 Design Pattern (formerly Applicaition Design Pattern) ...... 23 50 6.1 Protocol Flexibility ...... 23 51 6.2 General Rules / Best Practices ...... 23 52 6.3 Uniform Resource Identifiers ...... 24 53 6.3.1 Naming Conventions ...... 24 54 6.4 Standard URIs ...... 24 55 6.4.1 Active List ...... 24 56 6.4.2 Mirroring ...... 25 57 6.5 List Resources ...... 25 58 6.6 Query String Parameters ...... 25 59 6.7 Resource Design Rules ...... 26 60 6.8 HTTP Response Codes ...... 27 61 6.8.1 Common Responses ...... 27 62 6.8.2 Minimal Understanding ...... 29 63 7 NEW APP SUPPORT SECTION ...... 30 64 8 Device Requirements ...... 31 65 8.1 Client / Server ...... 31 66 8.2 Sleepy End Devices ...... 31 67 8.3 Function Sets ...... 31 68 8.4 Devices Types ...... 32 69 8.5 System Services ...... 34 70 9 Security (formally: Application Message Security) ...... 35 71 9.1 Network authentication and authorization...... 35 72 9.2 Application Authentication and Authorization context ...... 35 73 9.3 Application Authentication ...... 36 74 9.4 Application Authorization ...... 37

Smart Energy Profile 2.0 Page 4 Draft Application Protocol Specification September, 2011 Draft ZigBee-11167

75 9.5 Security Attributes ...... 37 76 9.5.1 Registration attributes ...... 37 77 9.5.2 Access Control List (ACL) attributes ...... 37 78 9.6 Cipher suites ...... 41 79 9.6.1 ECC cipher suite ...... 41 80 9.6.2 RSA cipher suite ...... 41 81 9.7 Certificate types ...... 41 82 9.7.1 Device Certificate ...... 42 83 9.7.2 Self-signed Certificate ...... 43 84 9.8 Default Security Policy ...... 43 85 9.9 Registration ...... 44 86 9.9.1 EndDevice list ...... 46 87 10 Discovery...... 48 88 10.1 Service Type ...... 48 89 10.2 Sub-Types ...... 48 90 10.3 TXT Record...... 49 91 10.4 Service Name ...... 50 92 11 Support Resources ...... 52 93 11.1 Device Capabilities Function Set ...... 52 94 11.1.1 DeviceCapability Resource ...... 52 95 11.2 End Device Resource (formerly EndDevice Resource) ...... 53 96 11.2.1 Overview ...... 53 97 11.2.2 Dependencies ...... 53 98 11.2.3 URI Structure and Actions ...... 53 99 11.3 EndDeviceGroupList ...... 57 100 11.3.1 Overview ...... 57 101 11.3.2 Dependencies ...... 57 102 11.3.3 Sequence Diagrams ...... 57 103 11.3.4 URI Structure and Actions ...... 57 104 11.3.5 Subscription / Notification Behavior ...... 58 105 11.3.6 Application Guidelines / Behavior ...... 58 106 11.4 Subscription / Push Mechanism ...... 60 107 11.4.1 Overview ...... 60 108 11.4.2 Subscription Resource ...... 60 109 11.4.3 Push Resource ...... 62 110 11.4.4 Conditional Subscription / Report by Exception ...... 62 111 11.4.5 Subscriptions with Limited Notifications ...... 63 112 11.4.6 Subscription Rules ...... 64 113 11.5 Response ...... 66 114 12 Common Resources ...... 67 115 12.1 Time Function Set ...... 67 116 12.1.1 Time Resource ...... 67 117 12.1.2 Page List Ordering ...... 67 118 12.2 DeviceInformation Function Set ...... 69 119 12.2.1 Device Information Resource ...... 69 120 12.3 Power Status ...... 70 121 12.4 NetworkStatus ...... 71 122 12.5 LogEvent Log ...... 72

Smart Energy Profile 2.0 Page 5 Draft Application Protocol Specification September, 2011 Draft ZigBee-11167

123 12.6 Configuration Resource ...... 76 124 12.7 Software Download Function Set ...... 78 125 12.7.1 Overview ...... 78 126 12.7.2 File Format...... 78 127 12.7.3 File Names ...... 84 128 12.7.4 Signatures ...... 84 129 12.7.5 Files Function Set ...... 86 130 12.7.6 Available Files Resource ...... 87 131 12.7.7 File Status Resource ...... 89 132 12.7.8 File Activation Resource ...... 90 133 13 Smart Energy Resouces (formerly:Application Layer Business Objective Messages) ...... 93 134 13.1 Common Functionality (formerly: Common Application Functionality) ...... 93 135 13.1.1 Overview ...... 93 136 13.1.2 Active URIs ...... 93 137 13.1.3 Event Rules and Guidelines ...... 94 138 13.1.4 Randomization ...... 98 139 13.1.5 Multiple ESIs ...... 99 140 13.2 Demand Response and Load Control ...... 103 141 13.2.1 Overview ...... 103 142 13.2.2 Dependencies ...... 103 143 13.2.3 URI Structure and Actions ...... 103 144 13.2.4 Subscription / Notification Behavior ...... 104 145 13.2.5 Application Guidelines / Behavior ...... 105 146 13.3 Metering Function Set ...... 111 147 13.3.1 Overview ...... 111 148 13.3.2 Dependencies ...... 111 149 13.3.3 Sequence Diagrams ...... 111 150 13.3.4 URI Structure and Actions ...... 113 151 13.4 Pricing Function Set ...... 135 152 13.4.1 Overview ...... 135 153 13.4.2 Dependencies ...... 135 154 13.4.3 Sequence Diagrams ...... 135 155 13.4.4 URI Structure and Actions ...... 135 156 13.4.5 Subscription / Notification Behavior ...... 137 157 13.4.6 Paging List Ordering...... 137 158 13.4.7 Application Guidelines / Behavior ...... 138 159 13.5 Messaging Function Set ...... 142 160 13.5.1 Overview ...... 142 161 13.5.2 Dependencies ...... 142 162 13.5.3 URI Structure and Actions ...... 142 163 13.5.4 Subscription / Notification Behavior ...... 146 164 13.5.5 Application Guidelines / Behavior ...... 146 165 13.6 Billing Function Set ...... 148 166 13.6.1 Overview ...... 148 167 13.6.2 Dependencies ...... 149 168 13.6.3 Sequence Diagrams ...... 150 169 13.6.4 URI Structure and Actions ...... 151 170 13.6.5 Customer Account Resource ...... 151

Smart Energy Profile 2.0 Page 6 Draft Application Protocol Specification September, 2011 Draft ZigBee-11167

171 13.6.6 BillingPeriod Resource ...... 152 172 13.6.7 Charge Resource ...... 153 173 13.6.8 TargetReading Resource ...... 153 174 13.6.9 ProjectionReading Resource ...... 153 175 13.6.10 HistoricalReading Resource ...... 154 176 13.6.11 Subscription / Notification Behavior ...... 154 177 13.6.12 Application Guidelines / Behavior ...... 154 178 13.7 Prepayment Function Set ...... 157 179 13.7.1 Overview ...... 157 180 13.7.2 Dependencies ...... 157 181 13.7.3 Sequence Diagrams ...... 157 182 13.7.4 URI Structure and Actions ...... 157 183 13.7.5 URI Structure ...... 157 184 13.7.6 URI Actions ...... 158 185 13.7.7 Subscription / Notification Behavior ...... 160 186 13.7.8 Application Guidelines / Behavior ...... 161 187 13.8 DER Control: (formerly: Distributed Energy Resources Function Set) ...... 165 188 13.8.1 Overview ...... 165 189 13.8.2 Dependencies ...... 166 190 13.8.3 Application Guidelines / Behavior ...... 170 191 13.8.4 PEV ANNEX ...... 176 192 14 Manufacturer – Specific Proprietary Extensions ...... 178 193 SE 2.0 Development Plan (Wuxi Agreement) ...... 179 194 15 Compression Mechanism ...... 181 195 15.1 Options for Compression of HTTP Data at the SE2.0 Application layer ...... 181 196 16 Appendices [INFORMATIVE] ...... 182 197 16.1 Transaction Sequence Examples ...... 182 198 16.2 Pricing Implementation Guidelines ...... 182 199 16.3 PEV Implementation Guidelines (subject to work with SAE and ISO/IEC) ...... 182 200 16.3.1 PEV – Plug-in Electric Vehicle ...... 182 201 16.4 Fixed Schemas ...... 182 202

Smart Energy Profile 2.0 Page 7 Draft Application Protocol Specification September, 2011 Draft ZigBee-11167

203 List of Tables 204 205 Table 10-1: Mapping of Function Sets to Device Types...... 33 206 Table 12-1: Registration Attributes...... 37 207 Table 12-2: Registration Descriptor Entry...... 37 208 Table 12-3: ACL Attributes...... 37 209 Table 12-4: SpecificIDDescriptor Entry...... 38 210 Table 12-5: Device Certificate Format...... 42 211 Table 12-6: Self-signed Certificate Format...... 43 212 Table 12-7: Attribute values for Default Security Policy...... 44 213 Table 7-1: Service sub-types and their corresponding SEP 2.0 function sets...... 48 214 Table 7-2: Other parameters that SHALL be included in the TXT record...... 49 215 Table 13-1: URI Structure Table for the DeviceCapability Resource...... 52 216 Table 9-1: URI Structure Table for EndDevice List...... 53 217 Table 11-1: URI Structure Table for End Device Groups...... 57 218 Table 13-2: URI Structure Table for the Time Resource...... 67 219 Table 13-3: URI Structure Table for the Base Resource...... Error! Bookmark not defined. 220 Table 13-4: URI Structure Table for the DeviceInformation Resource...... 69 221 Table 13-5: URI Structure Table for the PowerStatus Resource...... 70 222 Table 13-6: URI Structure Table for the NetworkStatus Resource...... 71 223 Table 13-7: URI Structure Table for the LogEventLog Resource...... 73 224 Table 13-8: LogEvent Codes...... 75 225 Table 13-9: URI Structure for the Configuration Resource...... 76 226 Table 13-10: Sample File...... 78 227 Table 13-11: Header Fields...... 79 228 Table 13-12: File Type Values...... 80 229 Table 13-13: RECOMMENDED File Version Definition...... 80 230 Table 13-14: Sub-element format...... 81 231 Table 13-15: File Data...... 82 232 Table 13-16: ECDSA Signature...... 82 233 Table 13-17: ECDSA Signer Certificate Sub-element...... 83 234 Table 13-18: RSA Signature...... 83 235 Table 13-19: RSA Signer Certificate Sub-element...... 83 236 Table 13-20: URI Structure Table for the Available Files Resource...... 88 237 Table 13-21: Query Parameters...... 88 238 Table 13-22: URI Structure Table for the File Status Resource...... 90 239 Table 13-23: URI Structure Table...... 91 240 Table 13-24: Query Parameters...... 91 241 Table 11-2: URI Structure Table for Response...... Error! Bookmark not defined. 242 Table 11-3: URI Structure Table for Demand Response and Load Control...... 103 243 Table 11-4: Event Status Table...... 109 244 Table 11-5: URI Structure Table for Metering...... 113 245 Table 11-6: URI Structure Table for Meter Mirroring...... 121 246 Table 11-7: Reading Information Types...... 126 247 Table 11-8: Relevant UOMs...... 127 248 Table 11-9: TOU Reading Types...... 129

Smart Energy Profile 2.0 Page 8 Draft Application Protocol Specification September, 2011 Draft ZigBee-11167

249 Table 11-10: TOU and Block Reading Types...... 131 250 Table 11-11: URI Structure Table for the Pricing Function Set Resources...... 135 251 Table 11-12: URI Structure Table for Billing Period Resource...... 152 252 Table 11-13: URI Structure Table...... 153 253 Table 11-14: URI Structure Table...... 153 254 Table 11-15: URI Structure Table...... 154 255 Table 11-16: URI Structure Table...... 154 256 Table 11-17: URI Structure Table for the Prepayment Resource...... 157 257 Table 11-18: URI Structure Table for the DER Resource...... 166 258 Table 11-19: Event Status Table...... 175 259

Smart Energy Profile 2.0 Page 9 Draft Application Protocol Specification September, 2011 Draft ZigBee-11167

260 List of Figures 261 Figure 1.4-1 – Smart Energy Profile Layer Model ...... 12 262 Figure 11.3-1: Application Guidelines / Behavior for the Response resource.Error! Bookmark 263 not defined. 264 Figure 11.5-1: Use Case – GET Meter Reading...... 112 265 Figure 11.5-3: Enumerated ReadingType fields and Quality Codes...... 128 266 Figure 11.8-1: Billing Data...... 150 267 Figure 11.8-2: Billing Readings...... 151 268 Figure 11.10-1: Application Guidelines / Behavior for the DER Resource...... 170 269 Figure 12.2-1: Application authentication and authorization context...... 35 270 Figure 12.2-3- Application authentication and authorization context with registration ...... 45 271 Figure 12.2-3- Device authentication with registration procedure examples using HTTPS using 272 port 443 46 273 Figure 13.4-1: Sequence Diagram - Files Function Set...... 87 274 Figure 13.4-1: Allowed and dissallowed extensions ...... 179 275 Figure A-A-1: Registration / Joining the HAN...... Error! Bookmark not defined. 276 Figure A-A-2: Sequence Diagrams 1...... Error! Bookmark not defined. 277 Figure A-A-4: DER Status...... Error! Bookmark not defined. 278 Figure A-A-5: Charge Reservation...... Error! Bookmark not defined. 279280

Smart Energy Profile 2.0 Page 10 Draft Application Protocol Specification September, 2011 Draft ZigBee-11167

281 1 Introduction

282 1.1 Purpose 283 The purpose of this document is to define the application protocol used by the Smart Energy Profile 284 release 2.0. The Smart Energy Profile Application Protocol is designed to meet the requirements stated 285 in the Smart Energy Profile 2.0 Marketing Requirements Document [ZBHP MRD] and the Smart Energy 286 Profile 2.0 Technical Requirements Document [ZB 095449]. Per Req[DataModel-1], this application 287 protocol is built to map directly to IEC 61968 [61968], the common information model and shall follow a 288 RESTful architecture [REST].

289 1.2 Scope 290 With respect to the OSI network model, the Smart Energy Profile 2.0 Application Protocol is primarily a 291 seven layer protocol built on top of an Internet Protocol (IP) stack. This is depicted in Figure 1-1 as the 292 'APPLICATION' layer of the Smart Energy Profile Layer Model with TCP/IP providing functions in the 293 'TRANSPORT' and 'NETWORK' layers. Depending on the physical substrate in use (e.g., 802.15.4, 294 802.11, 1901, etc.), a variety of lower layer protocols may be involved in providing a complete solution. 295 Generally, lower layer protocols are not discussed in this document except where there is a direct 296 interaction with the application protocol. The scope of this document is defining the mechanisms for 297 exchanging application messages, the exact messages exchanged including error messages, and the 298 security features used to protect the application messages.

299 1.3 Context Overview 300 The Smart Energy Profile 2.0 Application Protocol is proposed to the ZigBee Alliance and the HomePlug 301 Powerline Alliance to meet the needs specified in the SEP 2.0 MRD and TRD. The Smart Energy Profile 302 2.0 has been identified as a “standard for implementation” in NIST’s Framework and Roadmap for Smart 303 Grid Interoperability Standards [NIST 1108]. As such, this document may be useful for anyone 304 developing a Smart Grid solution.

305 1.4 Document Organization 306 This document has been organized to match the expected specification, test, and certification documents. 307 With its focus on the Application Layer, the Smart Energy Profile 2.0 Application Protocol Specification 308 maps primarily to the application layer of these other documents and will rarely address other layers.

Smart Energy Profile 2.0 Page 11 Draft Application Protocol Specification September, 2011 Draft ZigBee-11167

Application Layer

Transport Layer

Network Layer

Adaptation Layer

Link Layer 309 310 311 Figure 1.4-1 – Smart Energy Profile Layer Model 312 313 To retain continuity with the TRD, where explicit requirements are being addressed, a requirements cross- 314 reference may be included. Requirement cross-references will be in italics with the prefix Req and the 315 requirements identifier in brackets, for example Req[C-1]. Section 6 describes the design patterns used in 316 this specification. Details for usage of mDNS and DNS-SD in SEP 2.0 are described in Section 7 with the 317 requisite references. Section 8 describes the design and use of resources that support a generic, 318 lightweight subscription/push mechanism for use throughout the specification. The EndDevice resource 319 which is used to provide an interface to exchange information related to a particular client device is 320 described in Section 9. A physical end device-to-function set mapping is provided in Section 10, in 321 addition to serving as a general guide to the remainder of the document. Section 11 describes details 322 (including application guidelines) for each function set. These function sets are described in the 323 subsections to Section 11. Section 12 describes the security features that are provided at the application 324 layer and that are required for use over all networks. A number of supporting functions (in addition to the 325 function sets described in Section 11) which facilitate the operation of the SEP 2.0 application are 326 described in Section 13. Schema requirements for updates to the Smart Energy application profile are 327 described in Section 14.

328 1.5 Requirement Language 329 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 330 "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document, when in a 331 requirements block, constitute normative text and are to be interpreted as described in [RFC 2119]. 332 All statements and descriptions made in this document on Smart Energy Profile, SEP, or SE are 333 references to the Smart Energy Application Profile 2.0.

334 1.6 Typography Conventions Used

335 Example URIs, protocol requests, protocol responses, and XML are presented in fixed-width Courier New 336 font, with a size of 8.

Smart Energy Profile 2.0 Page 12 Draft Application Protocol Specification September, 2011 Draft ZigBee-11167

337 1.7 Design Principles 338 As per [ZB 095449] Section 10.1, the Smart Energy Profile 2.0 Application Protocol will follow a 339 RESTful architecture [REST]. The TRD lists a large number of general design principles. Several 340 specific ones are important for the application protocol: 341 1. While devices MAY maintain state, interfaces SHOULD be stateless. 342 2. URI structure SHOULD be clear but as efficient as possible. 343 3. Keep implementations simple. Minimize codespace and memory requirements. 344 4. Minimize the number of transactions required to achieve a given function.

345

Smart Energy Profile 2.0 Page 13 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

346 2 Acknowledgements 347 On behalf of the ZigBee Alliance, the HomePlug Powerline Alliance, and all of our liaison partners, we 348 would like to extend our thanks to all who participated in the development of this specification. 349 Representatives from many organizations have participated in weekly calls, face-to-face meetings, email 350 exchanges, and specialized editing sessions. Without the broad support from both member and external 351 organizations that care about the development of smart energy solutions, this work would not have been 352 possible. Select individuals stand out for their contributions to this document. 353 When the document was released, the Smart Energy Working Group Leadership was composed of the 354 following members: 355 Robby Simpson: Chair 356 Tim Gillman: Vice-chair 357 Rajagopal Iyengar: Technical Editor 358 Don Sturek: Program Manager 359 Tobin Richardson: Director, Smart Energy, ZigBee Alliance 360 Jeff Shudark: xxxxxxxxxxx 361 362 Our special thanks to the following members who contributed to the document: 363 Casey Anderson 370 Paul Duffy 377 Tony Mauro 364 Gary Birk 371 Gene Falendysz 378 Ricardo Montano 365 Robert Cragie 372 Matthew Gillmore 379 Zahra Makoui 366 Paul Carreon 373 Tom Herbst 380 Ivan O’Neill 367 Michael Cowan 374 Ken Holbrook 381 Michael Stuber 368 Wayne Dennison 375 Shawn Hu 382 Steven Van Ausdall 369 Jeff Drake 376 Jeff King 383 Mark Ward 384 385 386 387 388 389 390 391 392

Smart Energy Profile 2.0 Page 14 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

393 3 Document Revision History 394 Revision Version Description 0 Original Version 0.7 r0.4 Editorial and technical text changes based on ZigBee editors' review 0.7 r14.0 Editorial changes to the title page and preamble Section (nomenclature changed from SE to SEP) 0.7 R16 Editorial and technical changes included from September 2011 letter ballot 0.7 R17 Editorial and Technical updates agreed to from October 2011 Barcelona members meeting. Updates include: Sections 10.0 (Discovery), 11.1 (Device Capabilities), 12.1 (Time) ,12.2 (DeviceInformation), 13.2 (DRLC). 0.7 R18 PDF of revision R17

Smart Energy Profile 2.0 Page 15 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

395 4 References 396 External references in this document are tagged with a document reference identifier placed inline within 397 the text. The references Section maps these identifiers to document titles and provides hyperlinks to 398 where the source document may be obtained. Please note, not all referenced documents are freely 399 available. Selected documents MAY require a membership, subscription, or fee to obtain.

400 4.1 Smart Energy 2.0 Documents 401 [ZBHP MRD]... ZigBee+HomePlug Joint Working Group Smart Energy Profile Market Requirements 402 Document (http://www.zigbee.org/imwp/download.asp?ContentID=16081) 403 Public download available at: 404 http://www.zigbee.org/Standards/ZigBeeSmartEnergy/HomePlugMarketingRequirementDocument.aspx 405 [ZB 095449] ..... Smart Energy Profile Technical Requirements Document (095449) 406 Public download available at: 407 http://www.zigbee.org/Standards/ZigBeeSmartEnergy/20TechnicalRequirementsDoc.aspx 408 [ZB 105571] ..... Smart Energy 2.0 UML Model (105571) 409 [ZB 105629] ..... Smart Energy 2.0 XSD Package (105629) 410 [ZB 105636] ..... Reading Type Codes (105636)

411 4.2 HomePlug Powerline Alliance Documents 412 While the HomePlug MAC/PHYs are a specifically supported deployment option for the Smart Energy 413 Profile, currently there are no published HomePlug Powerline Alliance documents on which this 414 specification relies.

415 4.3 ZigBee Alliance Documents 416 [ZB 053474] ..... ZigBee Specification (053474r17) 417 Public download available at 418 http://www.zigbee.org/Specifications/ZigBee/download.aspx 419 [ZB 075123] ..... ZigBee Cluster Library Specification (ZCL) (075123r02) 420 Public download available at 421 http://www.zigbee.org/Products/ZigBeeClusterLibraryDownload.aspx 422 [ZB 075356] ..... Smart Energy Profile 1.1 (075356r15) 423 Public download available at 424 http://zigbee.org/Standards/ZigBeeSmartEnergy/PublicApplicationProfile.aspx 425 [ZB 094940] ..... SEP Intermediate Release 1 MRD (094940) 426 [ZB 095021] ..... SEP Intermediate Release 1 TRD (095021) 427 [ZB 095023] ..... ZigBee IP 2009 Specification (095023)

Smart Energy Profile 2.0 Page 16 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

428 [ZB 095310]… SEP Intermediate Release 1 Profile Specification (095310) 429 [ZB 095165] ..... Prepay requirements for the Intermediate release (095165) 430 [ZB 095208] ..... SE PM Additional Incremental Release Features (095208) 431 [ZB 095288] ..... Smart Water Meter MRD (095288r00) 432 [ZB 095264] ..... ZigBee OTA Upgrade Cluster Specification (095264) 433 [ZB 095328] ..... Smart Energy Profile UML Model (106049)

434 4.4 IEC Documents 435 [61850] ...... Communication networks and systems in substations - ALL PARTS 436 (http://webstore.iec.ch) 437 [61850-1] ...... Communication networks and systems in substations - Part 1: Introduction and overview 438 (http://webstore.iec.ch) 439 [61850-7-420] .. Communication networks and systems for power utility automation - Part 7: Basic 440 communication structure - Distributed energy resources logical nodes 441 (http://webstore.iec.ch) 442 [61968-1] ...... Application integration at electric utilities - System interfaces for distribution 443 management - Part 1: Interface architecture and general requirements 444 (http://webstore.iec.ch) 445 [61968-2] ...... Application integration at electric utilities - System interfaces for distribution 446 management - Part 2: Glossary (http://webstore.iec.ch) 447 [61968-3] ...... Application integration at electric utilities - System interfaces for distribution 448 management - Part 3: Interface for network operations (http://webstore.iec.ch) 449 [61968-4] ...... Application integration at electric utilities - System interfaces for distribution 450 management - Part 4: Interfaces for records and asset management 451 (http://webstore.iec.ch) 452 [61968-9] ...... Application integration at electric utilities - System interfaces for distribution 453 management - Part 9: Interfaces for meter reading and control 454 (http://webstore.iec.ch) 455 [61968-13]...... Application integration at electric utilities - System interfaces for distribution 456 management - Part 13: CIM RDF Model exchange format for distribution 457 (http://webstore.iec.ch) 458 [61968 UML] ... CIM Users Group Unified Modeling Language (UML) Model (61968-11) 459 http://cimug.ucaiug.org/CIM%20Model%20Releases/Forms/AllItems.aspx) 460 [61970-301]...... Energy management system application program interface (EMS-API) - Part 301: 461 Common information model (CIM) base (http://webstore.iec.ch) 462 [62055-21]……Electricity Payment Meters – A Framework for Standardization (http://webstore.iec.ch)

Smart Energy Profile 2.0 Page 17 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

463 4.5 IETF Documents 464 [COAP] ...... Constrained Application Protocol (CoAP), Z. Shelby, B. Frank. Constrained RESTful 465 Environments WG. (http://tools.ietf.org/wg/core) 466 [RFC 768] ...... User Datagram Protocol (http://www.tools.ietf.org/html/rfc768) 467 [RFC 792] ...... Internet Control Message Protocol (http://www.tools.ietf.org/html/rfc792) 468 [RFC 793] ...... Transmission Control Protocol (http://www.tools.ietf.org/html/rfc793) 469 [RFC 1042] ...... A Standard for the Transmission of IP Datagrams over IEEE 802 Networks 470 (http://www.tools.ietf.org/html/rfc1042) 471 [RFC 1350] ...... The TFTP Protocol (Revision 2) (http://www.tools.ietf.org/html/rfc1350) 472 [RFC 2119] ...... Key words for use in RFCs to Indicate Requirement Levels 473 (http://www. tools.ietf.org/html/rfc2119) 474 [RFC 2616] ...... Hypertext Transfer Protocol -- HTTP/1.1 (http://www.tools.ietf.org/html/rfc2616) 475 [RFC 2818] ...... HTTP Over TLS (http://www. tools.ietf.org/html/rfc2818) 476 [RFC 3117] ...... On the Design of Application Protocols (http://www.tools.ietf.org/html/rfc3117) 477 [RFC 3744] ..... Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol, G. 478 Clemm, J. F. Reschke, E. Sedlar, J. Whitehead, May 2004. 479 (http://tools.ietf.org/html/rfc3744) 480 [RFC 5246] ...... Transport Layer Security (TLS) Protocol V1.2 481 (http://www.tools.ietf.org/hmtl/rfc5246) 482

483 4.6 Other References 484 [S3API] ...... Amazon Simple Storage Service API Reference (API Version 2006-03-01), Amazon 485 Web Services (http://docs.amazonwebservices.com/AmazonS3/latest/API/) 486 [EXI] ...... Efficient XML Interchange (EXI) Format 1.0(http://www.w3.org/TR/2008/WD-exi- 487 20080919/) 488 [NIST 1108] ..... NIST Framework and Roadmap for Smart Grid Interoperability Standards, Release 1.0 489 (http://collaborate.nist.gov/twiki- 490 sggrid/pub/SmartGrid/IKBFramework/NISTFrameworkAndRoadmapForSmartG 491 ridInteroperability_Release1final.pdf) 492 [REST] ...... Representational State Transfer 493 (http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) 494 [RESTWEB] .... RESTful Web Services by Leonard Richardson and Sam Ruby. Copyright 2007 O’Reilly 495 Media, Inc., ISBN 978-0-596-52926-0. 496 (http://oreilly.com/catalog/9780596529260/) 497 [XEP-0134] ...... Protocol Design Guidelines (http://xmpp.org/extensions/xep-0134.html)

Smart Energy Profile 2.0 Page 18 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

498 4.7 UCA References 499 [OpenHAN]...... UtilityAMI 2008 Home Area Network System Requirements Specification 500 (http://www.utilityami.org/docs/UtilityAMI%20HAN%20SRS%20- 501 %20v1.04%20-%20080819-1.pdf)

502

Smart Energy Profile 2.0 Page 19 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

503 5 Definitions, Acronyms and Abbreviations

504 5.1 Acronyms and Abbreviations 505 This subsection provides a list of acronyms and abbreviations introduced in this document. For a 506 comprehensive treatment of acronyms and abbreviations used, please refer to Section 4 of the Smart 507 Energy Profile Technical Requirements Document [ZB 095449]. 508 ACL .... Access Control List 509 DGU .... Distributed Generating Unit 510 EXI ...... Efficient XML Interchange 511 HTTP .. Hypertext Transfer Protocol 512 UOM ... Units of Measure 513 URI ...... Uniform Resource Identifier 514 XML…. Extensible Markup Language

515 5.2 Definitions 516 A limited set of terms specific to this application specification are introduced below. For a 517 comprehensive treatment of the terms used, please refer to Section 4 of the Smart Energy Profile 518 Technical Requirements Document [ZB 095449]. 519 ACCESS CONTROL LIST 520 A security mechanism in which entities and authorizations (e.g., read, write, create, delete) 521 are related to resources to determine the entities’ allowed operations on the resources. 522 AUTHORIZATION SERVER 523 Server used to grant access to protected resources on Host. Performs pairing using TLS 524 handshake based on operation certificates with another Host. An Authorization Server MUST 525 be provided by every Host which has protected resources. 526 CLIENT 527 The device or host that interacts with a server to obtain information related to a resource 528 hosted by the server. 529 DEVICE 530 A physical device. In network context, a Node. In application context, a Host. 531 DEVICE CERTIFICATE 532 A digital certificate installed in the device at time of manufacturing. These certificates are 533 sent to the network authentication server for the purpose of authoritatively identifying a 534 device when it requests access to the network. Device certificates are not expected to change 535 over the lifetime of the device, unless dictated by a major revision to the Smart Energy 536 application profile specification

Smart Energy Profile 2.0 Page 20 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

537 END DEVICE GROUP 538 A logical addressing mechanism in Smart Energy 2.0 that allows a collection of devices to be 539 communicated with for a common purpose (e.g., devices enrolled in a common program). 540 FUNCTION SET 541 A grouping of data objects represented as a network resource which facilitates a given type of 542 transaction. Please see Section 8.38.3 for details. 543 HOST 544 The representation of a device in its application context. Typically represented by an IP 545 address or domain name. 546 IDEMPOTENT OPERATIONS 547 Idempotent Operations are those operations that a client can make once or many times and 548 have the same effect on server state, including no change in server state. Thus, a client can 549 perform the exact same idempotent operation one time, or many times, without fear that the 550 resulting server state will be different for any of the operations. The PUT and DELETE 551 methods are intended to be idempotent operations. Thus, one or many DELETE operations 552 SHOULD NOT have different results on the server state (deleted resource is no longer on 553 server), even though the response code may be different (e.g., 200 'OK' on first DELETE, and 554 404 'Not found' on subsequent DELETEs of the same resource). This also does not mean that 555 logs, etc., will not be updated, but rather that the client is simply requesting the same effect to 556 the state of the server each time. 557 LOGICAL DEVICE 558 A logical device is an application-oriented entity that contains a set of resources, and is 559 independently identifiable by URI on the network. There may be more than one logical 560 device on a host (device). Please see§8.4Section 8.4 for details. 561 NETWORK AUTHENTICATION SERVER 562 Server used to perform Network Authentication and control network access. 563 NODE 564 The representation of a device in its network context. Typically represented as an IP address. 565 RESOURCE 566 URI addresses aboject which is manipulated via the RESTful uniform interface of GET, PUT, 567 POST, and DELETE. 568 RESOURCE DISCOVERY 569 The process whereby Clients identify Resources being served on the network. Clients issue a 570 request to all devices on the network requesting resource(s) of interest. Servers hosting the 571 requested resource(s) respond with information necessary to access the Server and its 572 resource(s). 573 SAFE OPERATIONS

Smart Energy Profile 2.0 Page 21 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

574 Safe Operations are those operations that a client can make without implicitly changing the 575 server state. Thus, a client can perform a safe operation multiple times (or not at all) without 576 fear of unintended consequence. The GET method is intended to be a safe operation. Thus, 577 zero, one, or many GET operations SHOULD NOT affect the server state implicitly. This 578 does not mean that logs, etc., will not be updated, but rather that the client is not requesting 579 any change to the state of the server. Safe operations, by their nature, are idempotent, 580 however idempotent operations are not always safe, since they MAY result in a change to the 581 server state. 582 SERVER 583 The device or host that holds a resource and exposes representations of that resource.

Smart Energy Profile 2.0 Page 22 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

584 6 Design Pattern (formerly Applicaition Design Pattern)

585 6.1 Protocol Flexibility 586 The Smart Energy Profile is designed to implement a RESTful architecture. It is built around the core 587 actions of GET, PUT, POST, and DELETE (as used in [REST]), with the addition of a lightweight 588 subscription mechanism as discussed below. Any protocol that can implement the GET, PUT, POST, and 589 DELETE command set could likely be used with SEP 2.0, but HTTP is the required protocol for this 590 specification for interoperability. HTTP utilizes TCP as its transport protocol. As a result, TCP manages 591 the session providing delivery assurance and windowing. HTTP also provides a variety of caching and 592 cache management mechanisms that may be used. 593 Smart Energy Profile 2.0 devices SHALL be compliant with RFC 2616.

594 6.2 General Rules / Best Practices 595 PUT and DELETE often have difficulties with firewalls; however, as this standard is focused on HAN 596 and controlled networks, the benefit of clean verbs (including a clean delineation of safe and idempotent 597 verbs) outweighs the potential problems caused by misconfigured firewalls. 598 The interfaces and URIs specified throughout this document SHALL be symmetric. This specification 599 shall not make distinctions between servers, clients, devices, etc., when defining interfaces and URIs. On 600 any device, a particular resource always has the same behavior. In other words, the goal is to avoid 601 having a resource that has one behavior on a server and a different behavior on a client or different type of 602 server. The distinction between a server and a client arises dependent on whether a device exposes a 603 resource (server) or interacts with the resource (client). 604 The default mechanism for obtaining a resource representation SHALL be a pull mechanism. That is, a 605 client requests and retrieves data from a server or creates, modifies, or deletes data on a server. 606 The use of a subscription mechanism for retrieving a resource representation is also optionally supported 607 in many instances, where convenient and appropriate. 608 Clients that expect to have intermittent connections to the network (e.g., battery-powered sleepy devices, 609 mobile devices, etc.) SHALL use a pull mechanism as their default behavior for resource retrieval, as a 610 subscription/push mechanism may not be reliable. It should be noted that clients that expect to have 611 intermittent connections to the network may still POST, PUT, and DELETE resources, provided they 612 have the appropriate security permissions. 613 The TCP port 80 SHALL be used for all transactions. TCP Port 443 SHALL be used for all TLS secured 614 HTTP/TCP connections (HTTPS). This is consistant with the most commonly used ports in IP stacks. 615 Devices SHALL NOT assume the use of the URIs and their structures given throughout this specification. 616 All resources SHALL be self-describing as it is acknowledged that URIs, schemas, and resources MAY 617 change in the future. All resources SHALL contain links to their subordinate resources to support 618 flexibility in URIs and future extensibility. Thus, to allow for extensibility and granularity, all objects 619 SHALL be described in schemas and referenced via URIs. The URIs presented throughout this 620 specification SHOULD be regarded as RECOMMENDED. Thus, clients SHALL NOT assume that URIs 621 for resources are fixed on all servers or even on a given server (over time), but rather retrieve the 622 appropriate URIs through resource discovery and links within resources. For network efficiency, devices 623 MAY assume URIs are fixed on a particular server over time. If this ever returns an unexpected result, 624 then that device should perform resource discovery again.

Smart Energy Profile 2.0 Page 23 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

625 Version information SHOULD NOT be presented in the URI unless that version information is inherent 626 to the name of that resource. If necessary and for reasons of extensibility, version information should be 627 provided within the associated resources and/or schemas.

628 6.3 Uniform Resource Identifiers 629 6.3.1 Naming Conventions 630 While SEP 2.0 is not limited to HTTP, HTTP is a primary target for implementation. HTTP uses ASCII 631 text for transferring URIs between clients and servers, as well as for including options and details 632 regarding the message content. These transfers occur with every transaction. If the naming scheme used 633 for URIs is overly verbose, these transactions become needlessly inefficient on constrained networks. Of 634 course, if the naming scheme used is overly cryptic, the advantages of a text-based protocol are lost, and 635 it becomes difficult for someone troubleshooting to decipher a transaction. (Please note that the security 636 features used in SEP 2.0, as discussed in Section 9 and as provided for various media, e.g., ZigBee IP [ZB 637 095023], generally precluded.) 638 The following conventions are established for URI naming: 639 Rule:[URI-1] URI elements SHOULD be at most 4 characters, but recognizable to a 640 knowledgeable engineer. Element names as short as 2 characters are acceptable provided their 641 meaning is clear. 642 Rule[URI-2] URI elements SHOULD be constructed of consonants only, unless inclusion of a 643 vowel adds clarity, such as a leading vowel or well-known abbreviation. 644 Rule[URI-3] URI elements SHOULD be in all lower case. 645 Rule[URI-4] Root elements are more critical for abbreviation. 646 Some examples are provided to make clear the use of these rules as follows: 647 /msg – Message

648 /upt – Usage Point

649 /dr – Demand Response / Load Control 650 Rule[URI-5] For resources located on the same host, URIs given in resource representations 651 SHOULD be relative URIs. 652 Rule[URI-6] Clients SHOULD use relative URIs in HTTP requests. 653 Rule[URI-7] URIs SHALL NOT be greater than 255 bytes in length. In practice, URIs SHOULD 654 be much smaller.

655 6.4 Standard URIs 656 The use of the following URIs is considered to be a best practice for consistency and should be used, as 657 applicable, throughout this specification. 658 6.4.1 Active List 659 http{s}://{host}/{function set path}/actExampleEvents 660 This URI, when present, is used to address the resource that is designated as the list of currently active 661 events in time. For example, for a given list of events at the URI http{s}://{host}/{function set 662 path}/ExampleEvents, if the currently active events are at the URIs http{s}://{host}/{function set 663 path}/ExampleEvents/1 and http{s}://{host}/{function set path}/ExampleEvents/2, then the resource 664 addressed by http{s}://{host}/{function set path}/actExampleEvents SHALL contain a list that 665 contains identical objects as those addressed by http{s}://{host}/{function set path}/ExampleEvents/1

Smart Energy Profile 2.0 Page 24 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

666 and http{s}://{host}/{function set path}/ExampleEvents/2. Should another event become active, or 667 should there be no currently active event, then the URI http{s}://{host}/{function set 668 path}/ExampleEvents/actExampleEvents SHALL be updated as appropriate. The server SHALL be 669 responsible for updating the resource addressed at /actExampleEvents as necessary. Further description of 670 specific active lists, including specific resources and access permissions, is given in the appropriate 671 locations throughout this specification. 672 6.4.2 Mirroring 673

674 6.5 List Resources 675 Many resources throughout this specification are derived from the object. Throughout this 676 specification, these resources will collectively be referred to as list resources. 677 The following attributes are defined for list resources:

678  all – used to indicate the total number of items (subordinate resources) that exist in the overall list 679 resource (not necessarily the addressed list, as query string parameters, etc., MAY limit the 680 number of subordinate resources for the specified address). This attribute applies to the list 681 resource addressed. Therefore, if an active list is addressed, the ‘all’ attribute contains the total 682 number of items in the active list.

683  results – used to indicate the number of items (subordinate resources) included in this 684 representation of the resource.

685 6.6 Query String Parameters 686 Query string parameters are parameters added to a URI to provide filtering of a given resource. As query 687 string parameters are sent uncompressed in the URI and can unintentionally lead to non-RESTful designs, 688 their use in this specification is limited. 689 To provide clients with a way to control the amount of data returned, query string parameters are defined 690 to provide a paging mechanism. Each of the resources derived from the object in this specification 691 has a specified primary and secondary key defined. Lists are always ordered based by these keys. The 692 paging mechanism allows GET requests to specify the range of subordinate resources within the list based 693 on their ordinal position in the list. The general syntax of a paging query is as follows: 694 {URI}?s={x}&a={y}&I={z} 695 Where {URI} represents a URI used to address a list resource, represent query string parameters (further 696 defined below), and {x}, {y}, and {z} represent query string parameter values (further defined below for 697 their specific query string parameters). 698 The following query string parameters are defined for use with resources derived from the object:

699  s – (“start”) used to indicate that only items with an ordering greater than or equal to the given 700 parameter should be included in the addressed list resource. This parameter specifies the index 701 into a list of resources (similar to an index into an array) and specifies the first item in the list, 702 based on the defined primary and secondary keys of the list resource. The first index of the list 703 SHALL be designated with a value of ‘0’. If this query string parameter is not specified, the 704 default start value SHALL be ‘0’.

705  a – (“after”) used to indicate that only items occurring after the given date/time parameter should 706 be included in the addressed list resource. This query string parameter is only applied to list 707 resources that have a time-based primary key for ordering. The format of the parameter SHALL

Smart Energy Profile 2.0 Page 25 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

708 be a 64-bit hexadecimal number with identical semantics as that of the TimeType (see Section 709 13.2 and the XML schema).

710  l – (“limit”) used to indicate the maximum number of items that should be included in the 711 addressed list resource. If this query string parameter is not specified, the default limit SHALL 712 be ‘1’. 713 If both a “start” query string parameter as well as an “after” query string parameter are used 714 simultaneously, then the “after” query string parameter SHALL have precedence. Readers should note 715 that the “after” query string parameter SHOULD NOT be used for paging through a list. As some list 716 resources MAY contain multiple subordinate resources with the same time-based primary key, it is 717 RECOMMENDED that clients wishing to paginate a list resource while using the “after” query string 718 parameter should keep the value for the “after” query string parameter constant while changing the “start” 719 query string parameter. 720 If a particular query string parameter is used more than once, then the first occurrence of the query string 721 parameter SHALL be used (in left-to-right order). 722 Should an empty list representation be requested (either through the use of query string parameters such 723 as ‘l=0’ or when the list itself is empty), the server SHALL return no subordinate representations, but 724 SHALL return any other elements that may be defined for the list. 725 The following example demonstrates the use of query string parameters with list resources.

726 Imagine a list resource at the URI /list that has subordinate resources at /list/fffe, /list/ffff, 727 /list/0, /list/1, /list/2, and /list/3 and the resources themselves are in that order (a likely scenario 728 that may be caused by addresses rolling over).

729 An HTTP GET to /list?s=0&l=1 would return a list representation with a sole subordinate representation of 730 the resource that can be directly addressed at /list/fffe.

731 An HTTP GET to /list?s=0&l=5 would return a list representation with subordinate representations of the 732 resources that can be directly addressed (in order) at: /list/fffe, /list/ffff, /list/0, /list/1, and 733 /list/2.

734 An HTTP GET to /list?s=5&l=1 would return a list representation with a sole subordinate representation of 735 the resource that can be directly addressed at /list/3.

736 An HTTP GET to /list?s=5&l=5 would return a list representation with a sole subordinate representation of 737 the resource that can be directly addressed at /list/3.

738 6.7 Resource Design Rules 739 The following rules apply to the design and use of list resources:

740  List resources SHALL support the defined query string parameters, thus always supporting 741 paging.

742  List resources SHALL include an ‘href’ attribute for all subordinate items.

743  List resources SHALL have defined ordering (including ascending vs. descending) for their 744 subordinate resources, with both a primary and secondary key, as defined by their respective 745 function sets.

746  List resources SHALL contain the full representation of their top-level subordinate resources, 747 according to the rules for the subordinate resource.

Smart Energy Profile 2.0 Page 26 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

748  The URI of a subordinate resource SHALL NOT imply ordering (though the subordinate 749 resources themselves may be ordered).

750  The URI of a subordinate resource SHALL NOT be re-used for a new resource until after at least 751 65535 (0xFFFF) new subordinate resources have been created for a given resource type.

752  When queried, list resources that contain ordered lists SHALL return subordinate resources in 753 order. 754 The following rules apply to the design and use of non-list resources:

755  Non-list resources SHALL NOT support the defined query string parameters.

756  Non-list resources SHALL contain the full representation of their elements, with the exception of 757 elements derived from the IdentifiedObject class. Elements derived from the IdentifiedObject 758 class SHALL contain only an ‘href’ attribute and, if the element is a list resource, an ‘all’ 759 attribute.

760 6.8 HTTP Response Codes 761 Response codes are expected to be generalized across RESTful platforms. The specific uses detailed 762 below are likely to be generalized. In the interest of clarity and completeness, they are included here. 763 Please note that these response codes follow general best practices for RESTful interfaces, though they 764 are tuned to address some of the limitations of the embedded space. 765 SEP 2.0 clients, like any HTTP client, may see any HTTP response code defined by [RFC]. However, this 766 section attempts to highlight those that are felt to be more important or that need special attention from 767 developers. However, when used or encountered, all use of and response to HTTP response codes should 768 be specification and RFC compliant. 769 6.8.1 Common Responses 770 The following HTTP response codes are those considered to be of utmost importance for this 771 specification. 772 6.8.1.1 1xx (Informational) 773 These response codes are informational in purpose and are used to indicate that the server is continuing to 774 process in some fashion. 775 [RFC 2616] states, “A client MUST be prepared to accept one or more 1xx status responses prior to a 776 regular response, even if the client does not expect a 100 (Continue) status message. Unexpected 1xx 777 status responses MAY be ignored by a user agent.” 778 6.8.1.2 200 (“OK”) 779 This response code is sent to indicate a successful transaction. 780 This response code is often used in response to a successful GET request, with the entity-body containing 781 a representation of the requested resource. Use of this response code in response to PUT, POST, or 782 DELETE requests is discouraged, to avoid the potentially unnecessary traffic generated by returning the 783 resource representation in the entity-body (see 201 (“Created”) and 204 (“No Content”)). 784 6.8.1.3 201 (“Created”) 785 This response code is sent to indicate a new resource has been created, at the client’s request with a PUT 786 or POST. 787 The Location header SHOULD be used in conjunction with this response code to indicate the URI of the 788 newly created resource. The inclusion of a representation of the newly created resource in the entity-body 789 of the response is discouraged, to conserve bandwidth.

Smart Energy Profile 2.0 Page 27 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

790 RFC 2616 states, “If a new resource is created, the origin server MUST inform the user agent via the 201 791 (Created) response.” 792 6.8.1.4 204 (“No Content”) 793 This response code is sent to indicate a successful transaction, but one where the response does not 794 include an entity-body. 795 This response code is often used in response to a successful PUT or POST request, where the resource is 796 modified, not created. This response code is also sent in response to a successful DELETE request. This 797 response code is also sent in response to a successful GET request, where the resource exists but has an 798 empty representation. 799 6.8.1.5 301 (“Moved Permanently”) 800 This response code is sent to indicate that the requested resource has a new URI. Upon receipt of this 801 response code for resources a client would not expect to be re-located, clients SHOULD perform resource 802 discovery on the server, to determine which resources have changed location. 803 The Location header should be used in conjunction with this response code to indicate the new URI of the 804 requested resource. The entity-body of the response should be empty. 805 6.8.1.6 302 (“Redirect”) 806 This response code is used to redirect URI’s requested as HTTP from port 80 to port 443 with TLS. 807 6.8.1.7 400 (“Bad Request”) 808 This response code is used to indicate a client-side error and is used when no other 4xx response code is 809 appropriate. Often, this response code indicates that the representation sent by a client with a PUT or 810 POST is not appropriate or is malformed. 811 RFC 2616 states, “All Internet-based HTTP/1.1 servers MUST respond with a 400 (Bad Request) status 812 code to any HTTP/1.1 request message which lacks a Host header field.” 813 6.8.1.8 401 (“Unauthorized”) 814 This response code is used when a client does not have proper authorization to perform the request action 815 on a resource. 816 Note, if a server did not wish a client to know of the existence of the resource, it should instead send a 817 404 (“Not Found”) response code. 818 RFC 2616 states, “The response MUST include a WWW-Authenticated header field containing a 819 challenge applicable to the requested resource.” 820 6.8.1.9 404 (“Not Found”) 821 This response code is used to indicate that no resource can be found at the specified URI. 822 This response code MAY also be used in lieu of a 401 response code, server did not allow th method on 823 the addressed resource from the client. 824 6.8.1.10 405 (“Method Not Allowed”) 825 This response code is used to indicate that the resource does not allow the HTTP method the client used. 826 RFC 2616 states, “The response MUST include an Allow header containing a list of valid methods for the 827 requested resource.” 828 6.8.1.11 417 (“Expectation Failed”) 829 This response code is used to indicate that an expectation given in an Expect request-header field cannot 830 be met by the server or that the server does not support the given expectation.

Smart Energy Profile 2.0 Page 28 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

831 RFC 2616 states, “If a server receives a request containing an Expect field that includes an expectation- 832 extension that it does not support, it MUST respond with a 417 (Expectation Failed) status.” 833 6.8.1.12 500 (“Internal Server Error”) 834 This response code is used to indicate that the server has an internal problem and is a generic response. 835 6.8.1.13 501 (“Not Implemented”) 836 This response code is used when a client attempts to use a feature of HTTP (such as a method) that the 837 server does not support. 838 RFC 2616 states, “The recipient of the entity MUST NOT ignore any Content-* (e.g., Content-Range) 839 headers that it does not understand or implement and MUST return a 501 (Not Implemented) response in 840 such cases. 841 6.8.2 Minimal Understanding 842 Should a device wish to operate with minimal understanding of HTTP response codes, it need only 843 examine the first digit of the response code to understand the general category of the response and “treat 844 any unrecognized response as being equivalent to the x00 status code of that class, with the exception that 845 an unrecognized response MUST NOT be cached.” [RFC 2616]

Smart Energy Profile 2.0 Page 29 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

846 7 NEW APP SUPPORT SECTION

Smart Energy Profile 2.0 Page 30 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

847 8 Device Requirements

848 8.1 Client / Server 849 The rich variety of interactions on the HAN can make it difficult to define “client” and “server.” SEP 2.0 850 follows a RESTful paradigm. The server is the device that hosts a resource, and the client is the device 851 that obtains, extends, updates, or deletes representations of that resource. Devices may be both clients 852 and servers. 853 In keeping with a RESTful paradigm, request messages (generally) are not sent to clients. Clients poll 854 servers to obtain representations of the current state of a resource, and take action based on that state. For 855 example, an IHD might poll a meter to obtain a representation of the Metering resource or a DRLC device 856 might poll a DRLC server to obtain the current event list. 857 In order to reduce polling, which can be an inefficient use of resources, devices MAY also subscribe to a 858 resource. When a change to a resource is made (e.g., an addition to the DRLC event list or an update to 859 an event’s attribute), the server (notifier) will contact each client (subscriber) that is subscribed to 860 notifications for that resource. This exception to the RESTful paradigm is discussed in detail in Section 861 9.

862 8.2 Sleepy End Devices 863 Sleepy end devices must take care to not burden the PAN by subscribing to resources when they will 864 typically not be awaken to recieve notifications that may be produced. Furthermore a server MAY 865 remove an end-device after 3 successive TCP timeouts, as the client was unreachable.

866 8.3 Function Sets 867 Function sets are discrete groups of functionality that facilitate a given family of transactions. For 868 example, metering constitutes a function set, wherein a server device provides metering data. The 869 metering function set is comprised of a single RESTful URI hierarchy but it is made up of several actual 870 resources. 871 Current function sets in use in the Smart Energy Profile 2.0 are as follows:

872  Billing

873  Demand Response / Load Control 874  Device Management / Configuration 875  Diagnostic & Monitoring 876  Distributed Energy Resource 877  Firmware Download 878  Messaging 879  Metering 880  Plug-in Electric Vehicle 881  Prepayment 882  Pricing 883  Registration

Smart Energy Profile 2.0 Page 31 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

884  Response 885 Please note that devices are described by the function sets and roles that they implement. The function 886 sets/roles that a device implements MUST be declared on the PICS when they are tested for certification.

887 8.4 Devices Types 888 Smart Energy devices can be of a specific Device Type, or of several Device Types. This declaration is 889 placed in the Device Certificate and may be used as a means to determine a device’s qualification to 890 participate in specific programs. For example, a Service Provider MAY require that all devices enrolled 891 in a program be of a particular device type (e.g., thermostats). Please see Section 9 for the certificate 892 format. There is a minimum set of Function Set support required for each Device Type. 893 894 Device Types: 895  In-Premise Display (IPD) 896  Load Control Device (LCD) 897  Smart Thermostat (ST) 898  Metering (MTR) 899  Premise Energy Management System (PEMS) 900  Energy Services Interface (ESI) 901  PrePayment Terminal (PT) 902  Inverter (INV) 903  Electric Vehicle Supply Equipment (EVSE) 904  End-Use Measurement Device (EUMD) 905  Plug-in Electric Vehicle (PEV) 906  Distributed Energy Resource (DER) 907  Communications (Comms) Module

Smart Energy Profile 2.0 Page 32 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

908 Table 8-1: Mapping of Function Sets to Device Types. Device Types

M: Mandatory

1

M : Support at least one

2

M : Support both Client

and Server of at least one of

these Function Sets.

Support of any other

Function Set is

In Electric Vehicle InElectric

User Measurement Measurement User -

OPTIONAL. -

Premise Device Premise

-

In LoadControlDevice SmartThermostat Metering SmartAppliance Energy Premise System Management Interface EnergyServices PrePaymentTerminal Inverter Supply Vehicle Electric Equipment End Device Plug Resource Energy Distributed Module Comms

Base M M M Client Billing Server Client

Server Demand Client M M1 M1 M2 M Response / Load Server M2 M Control Device Client Management / Server Configuration Diagnostics & Client

Monitoring Server Distributed Client Energy Server M Resource Firmware Client

Function Sets Function Download Server Client M1 Messaging Server M Client M1 Metering Server M M Plug-In Electric Client M Vehicle Server M Client Prepayment Server Client M1 M1 M1 M2 Pricing Server M2 M M Client Registration Server Response Client Server 909

Smart Energy Profile 2.0 Page 33 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

910 8.5 System Services 911 The Smart Energy Profile 2.0 is designed to run in an Internet Protocol environment. Tasks such as 912 address assignment, network admission, and routing are assumed to be handled by lower layers, and as 913 such are out of scope for this specification. For ZigBee 802.15.4 networks, details are discussed in the 914 ZigBee IP Specification [ZB 95023]. More broadly, in a platform neutral way, expectations for the 915 Internet Protocol environment required by the Smart Energy Profile 2.0 are discussed in the ZigBee 916 Application Support Specification in Section 13. 917 The most critical service required by the Smart Energy Profile is Resource Discovery. The Smart Energy 918 Profile 2.0 is made up of a series of resources. Devices MAY choose to implement only a subset of the 919 resources available. A device on the network MUST be able to search for a given resource and determine 920 which other devices on the network provide that resource. The mechanism for performing these 921 operations is discussed at length in the ZigBee Application Support Specification [ZB 95446] , and it will 922 not be repeated here. However, in order to perform resource discovery, this specification MUST assign 923 1405 names to the resources. To this end, each function set is assigned a resource name, distinct from its 924 URI, 1406 to be used in the resource discovery process. The unit of discovery is the function set, which 925 is a collection of one or more closely related resources. Each function set is assigned a name which is 926 used b the discovery process to indentify a specific function set.

Smart Energy Profile 2.0 Page 34 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

927 9 Security (formally: Application Message Security) 928 Depending on the underlying physical network, messages may be encrypted at lower layers, in addition to 929 the security features provided specifically for the application layer. This Section describes the security 930 features that are provided at the application layer and that are REQUIRED for use over all networks.

931 9.1 Network authentication and authorization 932 Network authentication and authorization occurs according to the network access process, for example a 933 network access process is described in the ZigBee IP specification [ZB 095023]. Further discussion of 934 network authentication and authorization is outside of the scope of this document.

935 9.2 Application Authentication and Authorization context 936 Once authenticated and authorized through network access, a Node can freely communicate in the 937 network at the network layer. However, authentication and authorization at the application layer normally 938 needs to occur to allow hosts to communicate with each other either serving resources as a server host or 939 accessing resources as a client host. Registration with a utility or third party service provider may also be 940 needed to provide explicit device and user authorization at the application layer. 941 Resource access requiring authentication and security SHALL occur through requests from a client host 942 to the server host using HTTP over TLS [RFC 2818] (also known as HTTPS) using TLS version 1.2 943 [RFC 5246]. Resource access not requiring authentication or application layer security shall occur 944 through requests from a client host to the server host using HTTP [RFC 2616].

HTTPS Secure Client m, port X Resource A C server L

HTTP Unsecure Client n, port Y

Host

945 946 Figure 9.2-1: Application authentication and authorization context. 947 If a request is made to the port associated with HTTPS (typically port 443), it is considered an HTTPS 948 request and authentication SHALL have taken place. If authentication has not taken place, authentication 949 SHALL be initiated as described in Section 9.3. When authenticated, the request is then passed to the 950 ACL (access control list) associated with the resource. Ancillary information about the request obtained 951 from the secure session, notably the level of client authentication, SHALL also be passed to the ACL. 952 If the request is made to the port associated with HTTP (typically port 80), it is considered an HTTP 953 request and authentication SHALL NOT be REQUIRED and the request is then passed to the ACL 954 associated with the resource. Ancillary information about the request stating the client is unauthenticated 955 SHALL also be passed to the ACL.

Smart Energy Profile 2.0 Page 35 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

956 Authorization on a request-by-request basis is determined by the ACL settings for the resource, which 957 may be set up at the end of the authentication based on the level of client authentication. The Registration 958 List may be additionally used to authorize on a device-by-device basis.

Device Client Host IP address C IP address B

ACL initialized according to security policy HTTP Request (sp:n, dp:443) GET / Authorization granted based on ACL lookup Authentication

HTTP Response (sp:443, dp:n) 200 OK

HTTP Request (sp:n, dp:80) GET / Authorization for unsecured access denied HTTP Response (sp:80, dp:n) based on ACL lookup 404 Not Found

959 960 Figure 9.2-2: Device authentication procedure examples using HTTPS using port 443

961 9.3 Application Authentication 962 Application authentication only applies using HTTPS. It may be possible to authenticate at a higher level 963 using application layer authentication based on HTTP-only transactions but this is out of scope for this 964 specification. It is important to note that authentication occurs between server host (e.g. network 965 addressable device) and client host instance (i.e network addressable device and source port). 966 All hosts implementing server functionality SHALL use a Device Certificate. 967 The application authentication process is as follows: 968 1. The resource’s server host listens on the TCP port associated with HTTPS (typically port 443). 969 The client host initiates an HTTP request using a random unused source TCP port to the 970 resource’s server host using the TCP port associated with HTTPS. 971 2. If no TLS session is in place, a TLS handshake SHALL occur between the client host and server 972 host: 973 a. Authentication of the server host SHALL be done as part of the TLS handshake by 974 validating its Device Certificate using the inherent PKI. If security policy dictates, 975 additional validation such as OCSP MAY be required. 976 b. If the client host has a Device Certificate, authentication of the client host SHALL be 977 done as part of the TLS handshake by validating the client host’s Device Certificate using

Smart Energy Profile 2.0 Page 36 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

978 the inherent PKI. If security policy dictates, additional validation such as OCSP MAY be 979 required 980 c. If the client host has a Self-signed Certificate, the Self-signed Certificate SHALL be 981 validated for correctness. 982 d. If the client host does not have a certificate and the security policy allows, client host 983 authentication MAY NOT need to take place, or secondary client authentication MAY 984 take place after the TLS handshake.

985 9.4 Application Authorization 986 Pre-authorization for resources is normally set when the client host registers with the server host as 987 described in Section 12.3. If the security policy allows, authorization MAY occur immediately after 988 authentication based on implicit rules to allow a request to complete. This is to allow unregistered access 989 to resources based on security policy. If the client host uses a Self-signed Certificate, pre-authorization 990 using the GUID of the Self-signed Certificate MUST have taken place and authorization SHALL be 991 granted if the GUID of the presented Self-signed Certificate matches the GUID presented as part of 992 registration.

993 9.5 Security Attributes 994 Security attributes are conceptual variables which represent a mechanism to control registration and 995 access control lists. They do not necessarily represent how the attributes would be implemented. Access 996 methods to attributes (e.g. APIs) are out of scope for this specification. 997 9.5.1 Registration attributes 998 Table 9-1: Registration Attributes. Attribute Identifier Type Range Description Default aclRegistrationList 0x00 List - A table of (empty) RegistrationDescriptors each with information for a specific registration aclRegistrationListEntries 0x01 Integer Implementation Number of entries in 0 specific aclRegistrationList

999 1000 Table 9-2: Registration Descriptor Entry. Name Type Range Description Default GUID GUID - GUID of registering device - DeviceTypeList List - A list of required device types - DeviceTypeListEntries Integer - Number of entries in DeviceTypeList 0

1001 9.5.2 Access Control List (ACL) attributes 1002 Table 9-3: ACL Attributes. Attribute Identifier Type Range Description Default

Smart Energy Profile 2.0 Page 37 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

Attribute Identifier Type Range Description Default

aclDefaultMethod 0x00 Bitmap 0x0 – 0xf Bitmap of which methods 0x0 are supported: 0x01: GET 0x02: PUT 0x04: POST 0x08: DELETE aclDefaultAuthLevel 0x01 Integer 0 – 3 Authentication Level: 0 0: No authentication 1: User authentication 2: Self-signed Certificate 3: Device Certificate

aclDefaultDeviceType 0x02 Integer 0x0000 – Device type: 0 0xffff 0: Not specified aclSpecificIDList 0x03 List - A table of (empty) SpecificIDDescriptors each with information for a specific ID aclSpecificIDListEntries 0x04 Integer Implementation Number of entries in 0 specific aclSpecificIDList

1003 1004 Table 9-4: SpecificIDDescriptor Entry. Name Type Range Description Default IPv6Addr IPv6Addr - IPv6 Address of client host - Port Integer 0x0000 – Port of client host 0 0xffff Method Bitmap 0x0 – 0xf Bitmap of which methods are supported: 0x0 0x01: GET 0x02: PUT 0x04: POST 0x08: DELETE AuthLevel Integer 0 – 3 Authentication Level: 0 0: No authentication 1: User authentication 2: Self-signed Certificate

Smart Energy Profile 2.0 Page 38 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

Name Type Range Description Default 3: Device Certificate DeviceType Integer 0x0000 – Device type: 0 0xffff 0: Not specified GUID GUID - GUID of device originating incoming - request

1005 1006 The Access Control List (ACL) attributes provide a mechanism for granting and revoking privileges to 1007 use specified methods with a particular resource, through the use of access control lists (ACLs). Access 1008 control more granular than a resource is out of scope for this specification. These ACLs are intended for 1009 use throughout this specification. This mechanism is intended to allow granular access control for 1010 resources. The mechanisms for authentication and the binding of that authentication to a specified 1011 identity (such as an IP address) is specified above in Sections 9.2 and 9.1. 1012 ACLs are used to set default privileges and grant additional privileges, not to deny privileges. Thus, if a 1013 given host’s request does not explicitly meet the required privilege in the associated ACL, then that host 1014 does not have that privilege. Further, an empty ACL for a given resource SHALL mean that resource is 1015 not accessible to other hosts. In practice, this state only exists ephemerally and all ACLs SHALL be 1016 initialized appropriately at startup according to the security policy and SHALL be subsequently modified 1017 according to registration and authentication. 1018 Subordinate resources created dynamically SHALL inherit their ACL from their parent resource. 1019 ACLs may be statically fixed with a default operation for some resources and may be dynamic and 1020 extensible for others. If a resource does not have an ACL, access SHALL be granted to the resource 1021 unconditionally. 1022 Initialization of ACLs, beyond minimal requirements, is out of scope for this specification and is 1023 governed by overall security policy. Default settings for ACLs for particular function sets are described in 1024 Section 9.8. 1025 9.5.2.1 Source Independent authorization 1026 These are controls which are independent of the source identity (IP address and port) and thus can be 1027 configured in a Default or a SpecificID entry as shown in Table 12-4. 1028 In the following, ‘corresponding ACL entry’ means:

1029  The first SpecificID entry which matches the incoming HTTP request source IP address and port.

1030  Considered the Default entry otherwise. 1031 9.5.2.1.1 Method attribute 1032 The Method attribute is used to control which HTTP request method is allowed for Host access.

1033  GET

1034  PUT

1035  POST

1036  DELETE 1037 The HTTP method of an incoming HTTP request SHALL be checked and Method authorization SHALL 1038 be TRUE if the method is allowed in the corresponding ACL entry.

Smart Energy Profile 2.0 Page 39 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1039 9.5.2.1.2 AuthLevel attribute 1040 The AuthLevel attribute is used to control the authentication level REQUIRED of the client host’s 1041 incoming HTTP request.

1042  0: No authentication

1043  1: User authentication

1044  2: Self-signed Certificate

1045  3: Device Certificate 1046 If an incoming HTTP request is destined for the port associated with HTTPS (typically port 443), the 1047 incoming authentication level SHALL be set to the corresponding TLS session authentication level. If an 1048 incoming HTTP request is destined for the port associated with HTTP (typically port 80), the 1049 authentication level SHALL be set to ‘no authentication’ (0). 1050 The incoming authentication level SHALL be compared with the AuthLevel in the corresponding ACL 1051 entry and AuthLevel authorization SHALL be TRUE if the authentication level is greater than or equal to 1052 the AuthLevel in the corresponding ACL entry. 1053 9.5.2.1.3 DeviceType attribute 1054 The DeviceType attribute is used to control the device type required of the client host’s incoming HTTP 1055 request. 1056 If an incoming HTTP request is destined for port 443 (HTTPS), the incoming device type SHALL be set 1057 to the corresponding TLS session device type. If an incoming HTTP request is destined for port 80 1058 (HTTP), the device type SHALL be set to ‘not specified’ (0). 1059 If the DeviceType in the ACL is set to ‘not specified’, device type authorization SHALL be TRUE 1060 unconditionally. Otherwise the incoming device type SHALL be compared with the DeviceType in the 1061 corresponding ACL entry and DeviceType authorization SHALL be TRUE if the device type is equal to 1062 the DeviceType in the corresponding ACL entry. 1063 9.5.2.2 Source dependent authorization 1064 These are controls which are dependent upon the source identity (IP address and port) and thus can only 1065 be configured in a SpecificIDDescriptor entry. 1066 In the following, ‘corresponding ACL entry’ means:

1067  The first SpecificIDDescriptor entry which matches the incoming HTTP request source IP 1068 address and port. 1069 If there is no corresponding ACL entry, no further processing SHALL take place and the respective 1070 authorization SHALL be TRUE. 1071 9.5.2.2.1 GUID control 1072 The GUID attribute is used to control the GUID (globally unique ID) required of the client host’s 1073 incoming HTTP request. 1074 If an incoming HTTP request is destined for port 443 (HTTPS), the incoming GUID SHALL be set to the 1075 corresponding TLS session GUID. If an incoming HTTP request is destined for port 80 (HTTP), the 1076 GUID SHALL be set to ‘not specified’. 1077 If the GUID in the corresponding ACL entry is set to ‘not specified’, GUID authorization SHALL be 1078 TRUE unconditionally. Otherwise the incoming GUID SHALL be compared with the GUID in the 1079 corresponding ACL entry and GUID authorization SHALL be TRUE if the GUID is equal to the GUID in 1080 the corresponding ACL entry.

Smart Energy Profile 2.0 Page 40 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1081 9.5.2.3 aclDefault attributes 1082 The aclDefault attributes in the ACL are used for settings irrespective of the identity of the source of an 1083 incoming request and are used initially to authorize an incoming HTTP request. 1084 9.5.2.3.1 SpecificIDDescriptor Entry 1085 A SpecificIDDescriptor entry in the ACL is an additional entry used to allow specific additional checks to 1086 be done to authorize based on source identity (IP address and port) 1087 9.5.2.4 Authorization logic 1088 Authorization is granted if Method authorization, AuthLevel authorization, DeviceType authorization and 1089 GUID authorization are all TRUE. Access to the resource can then take place. 1090 If authorization is not granted, the server SHALL immediately respond: 1091 HTTP/1.1 404 Not Found 1092 as detailed in Section 6.8. Otherwise, processing SHALL continue.

1093 9.6 Cipher suites 1094 All devices SHALL support the TLS_ECDHE_ECDSA_WITH _AES_128_CCM_8 ciphersuite. Devices 1095 MAY additionally support the TLS_DHE_RSA_WITH _AES_128_CCM_8 ciphersuite. Devices SHALL 1096 NOT support any other TLS ciphersuite for the purpose of application-layer session establishment. 1097 9.6.1 ECC cipher suite 1098 The ECC cipher suite supported SHALL be TLS_ECDHE_ECDSA_WITH _AES_128_CCM_8 [draft- 1099 mcgrew-tls-aes-ccm-ecc]. The ECC cipher suite shall use elliptic curve secp256r1.

1100  All devices acting as a server host SHALL support the ECC cipher suite. In particular, all devices 1101 acting as a server host SHALL have an ECDSA server certificate.

1102  All devices acting as a client host SHALL support the ECC cipher suite for the purposes of 1103 validating an ECDSA server certificate.

1104  All devices acting as a client host should support the request for an ECDSA client certificate. 1105 9.6.2 RSA cipher suite 1106 The RSA cipher suite supported SHALL be TLS_ DHE_RSA_WITH _AES_128_CCM_8 [draft- 1107 mcgrew-tls-aes-ccm]. The RSA cipher suite may be used in addition to the ECC cipher suite.

1108  All devices acting as a server host may support the RSA cipher suite

1109  All devices acting as a client host may support the RSA cipher suite for the purposes of validating 1110 an RSA server certificate.

1111  All devices acting as a client host MAY support the request for an RSA client certificate.

1112 9.7 Certificate types 1113 There are two types of certificate used:

1114  Device Certificate

1115  Self-signed Certificate 1116 ZigBee-defined fields in subjectAltName and certificatePolicies fields SHALL be derived from the 1117 ZigBee PEN OID node: 1.3.6.1.4.1.37244

Smart Energy Profile 2.0 Page 41 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1118 For the purposes of a certificate, a device can be a single physical device on a single networked node 1119 device or it can be one virtual device of possibly many within a unit on a single networked node, e.g. an 1120 application residing on a PC, tablet or smartphone. 1121 A certificate may also be used for network authentication and authorization; how it is used is outside of 1122 the scope of this document. 1123 9.7.1 Device Certificate 1124 A Device Certificate is a CA-signed certificate that is usually provisioned into a device at manufacture. It 1125 may also be possible for a device to securely obtain a Device Certificate, e.g., when installing and 1126 registering an application. 1127 A Device Certificate is used to authenticate the Device itself, e.g., it validates that the Device is 1128 associated with the ID it has and the functionality it represents in the Device Certificate. 1129 Any other device validating the CA-signed Device Certificate must have the appropriate certificate chain 1130 to the CA root, e.g., be able to obtain the public key via the certificate of the next level up as identified by 1131 the Issuer field of the certificate. The Root CA MAY typically use a self-signed certificate or the Root CA 1132 public key may be provisioned into the device at manufacture. 1133 9.7.1.1 Device Certificate format 1134 The Device Certificate format SHALL be X.509v3 according to [RFC5280]. X.509v3 uses ASN.1 DER 1135 encoding according to X.690. Specifically, it SHALL have the following fields: 1136 Table 9-5: Device Certificate Format.

Field Subfield Value Version 2 (indicates v3) serialNumber eight octets containing random data with at least 20-bits of entropy Signature ecdsa-with-SHA256 (see [RFC 5008]) Issuer Dependent on CA validity notBefore Time of issue notAfter GeneralizedTime value of “99991231235959Z” Subject Dependent on manufacturer subjectPublicKeyInfo algorithmIdentifier = id-ecPublicKey (see [RFC 5480]) ECParameters = secp256r1 Public key for device non-critical extension subjectKeyIdentifier Set by CA for this certificate non-critical extension authorityKeyIdentifier subjectKeyIdentifier in CA certificate non-critical extension subjectAltName hardwareModuleName (see [RFC 4108]) critical extension certificatePolicies Contains device type for device authentication signatureAlgorithm ecdsa-with-SHA256 (see [RFC 5008]) (as signature field)

Smart Energy Profile 2.0 Page 42 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

signatureValue Signature over certificate up to signatureAlgorithm

1137 1138 9.7.2 Self-signed Certificate 1139 A Self-signed Certificate is a certificate generated along with a public/private key pair wholly within a 1140 device, e.g., when installing an application. Its subject field will be a GUID, which is then used for 1141 registration purposes. 1142 A Self-signed Certificate cannot be used to authenticate the Device itself and only represents user 1143 authentication when used in conjunction with registration. 1144 9.7.2.1 Self-signed Certificate format 1145 The Self-signed Certificate format SHALL be X.509v3 according to [RFC5280]. X.509v3 uses ASN.1 1146 DER encoding according to X.690. Specifically, it SHALL have the following fields: 1147 1148 Table 9-6: Self-signed Certificate Format.

Field Subfield Value Version 2 (indicates v3) serialNumber eight octets containing random data with at least 20-bits of entropy Signature ecdsa-with-SHA256 (see [RFC 5008]) Issuer Dependent on certificate issuer validity notBefore Time of issue notAfter GeneralizedTime value of “99991231235959Z” Subject Same as Issuer subjectPublicKeyInfo algorithmIdentifier = id-ecPublicKey (see [RFC 5480]) ECParameters = secp256r1 Public key for device non-critical extension subjectKeyIdentifier Set by device signatureAlgorithm ecdsa-with-SHA256 (see [RFC 5008]) (as signature field) signatureValue Signature over certificate up to signatureAlgorithm

1149

1150 9.8 Default Security Policy 1151 Service providers create security policies by balancing the requirements of their regulatory 1152 environment and the results of their risk assessments. Different regulatory environments may mandate 1153 requirements which trade ease of data access with information assurance. The use of TLS, ACLs, and 1154 other security controls gives the service provider the flexibility to meet these needs. Security policies

Smart Energy Profile 2.0 Page 43 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1155 are a combination of ACL attribute values and additional security controls dictated by the service 1156 provider. Implementation of security policies is out of scope of this specification. For the purpose of 1157 certification testing, the following table represents the default security policy for each function set. 1158 Servers shall support each default policy for all implemented function sets. 1159 Function Set aclDefaultAuthLevel TLS Registered Device Demand Response / Load Control 3 Mutual Yes Messaging 2 Server Yes Response 2 Mutual Yes Pricing 2 Server No Pre-Payment 3 Mutual Yes Metering 2 Mutual Yes Plug-In Electric Vehicles 3 Mutual Yes Distributed Energy Resource 3 Mutual Yes Billing 3 Mutual Yes

Registration 2 Mutual Yes Base 2 Server Yes Device Management / Configuration 2 Mutual Yes Firmware Download 2 Mutual Yes Diagnostics & Monitoring 2 Mutual Yes

1160 Table 9-7: Attribute values for Default Security Policy. 1161 The aclDefaultMethod attribute value should match the Allowed Methods for each resource enumerated 1162 in Section 10. The aclDeviceType attribute value should be ‘not specified’ (0). Servers shall support the 1163 default policies for certification testing. Servers may additionally support alternative policies. For 1164 example, to meet regulatory requirements a utility may mandate a policy which provides unauthenticated 1165 pricing information from a meter over the the port associated with HTTP (typically port 80) to any SEP 1166 2.0 device. Based on risk assessments, service providers may have differing policies for devices enrolled 1167 in high-incentive Demand Response / Load Control programs than those enrolled in low-incentive 1168 programs, to include additional requirements such as DeviceType authorization. Servers should provide 1169 the functionality to support multiple security policies to meet the requirements of different service 1170 providers.

1171 9.9 Registration 1172 Registration can generally occur with any resource and describes the procedure whereby an out-of-band 1173 procedure is used to convey client host registration information a priori to the server host which houses 1174 the resource which will subsequently be accessed by the client host. The registration information is the 1175 client host’s GUID, which uniquely identifies the client host. This is then used after authentication to 1176 populate the ACL with a device entry for that resource (i.e. whitelist) which ensures only registered 1177 devices can access the resource.

Smart Energy Profile 2.0 Page 44 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1178 This Section describes a typical registration procedure for a client host using a Device Certificate with an 1179 ESI-based server host. 1180 Registration for client hosts SHALL occur via an EndDevice resource which typically resides on an ESI 1181 associated with the utility, premises owner or third party service provider that is trusted to perform 1182 registration. The EndDevice resource may be co-hosted with the Network Authentication Server and 1183 therefore its operations may be combined if the security policy allows it.

Registration list

HTTPS Secure Client m, port X /edev A C server L

HTTP Unsecure Client n, port Y

Host 1184 1185 Figure 9.9-1- Application authentication and authorization context with registration

Smart Energy Profile 2.0 Page 45 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

ESI Client Host IP address A IP address B

Out of band registration HTTP Request (sp:m, dp:443) ACLs setup for /edev and GET /edev other resources as necessary based on Authentication successful authentication HTTP Response (sp:443, dp:m)

and matching registration 200 OK Authorization granted HTTP Request (sp:m, dp:443) based on ACL lookup POST /edev HTTP Response (sp:443, dp:m) Authorization to create 200 OK /edev instance is granted based on ACL lookup 1186 1187 Figure 9.9-2- Device authentication with registration procedure examples using HTTPS using port 443 1188 9.9.1 EndDevice list 1189 Client hosts locate HAN services by performing DNS Service Discovery (DNS-SD) queries to the HAN. 1190 A query may be issued non-specifically for any Smart Energy 2 device, or a Smart Energy 2 device 1191 supporting a specific function set. Successful DNS-SD queries SHALL return a link to the matching 1192 device’s DeviceCapability resource, along with the TCP ports used for HTTPS (and HTTP, if relevant) 1193 access. The client host can then resolve the URI of the EndDevice list (given as /edev for illustration 1194 purposes) for registration and authentication purposes and know which port(s) the server for the 1195 EndDevice list is listening on. 1196 The EndDevice list is the resource used by a client host to complete registration when the device owner 1197 wishes to register the device in a utility, premises owner or service provider program. in some cases, 1198 registration is REQUIRED for access. 1199 The EndDevice resource’s server host aclRegistrationList SHALL be pre-configured with:

1200  The client host GUIDs, which will become registered in the utility, premises owner or 1201 third party service provider program

1202  The required device types of the associated client host 1203 so at the point of registration, the EndDevice resource’s server host is able to perform authentication 1204 based on the Device Certificate and additional user authentication based on the client host GUID. 1205 The client host GUID is information which uniquely identifies the client host. The GUID SHALL be the 1206 SHA-256 thumbprint of the Device Certificate or the Self-signed Certificate. 1207 The EndDevice resource’s server host MAY allow access from client hosts which have not been pre- 1208 configured if the security policy allows. 1209 The registration procedure is as follows:

Smart Energy Profile 2.0 Page 46 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1210 1. The EndDevice resource’s server host (typically an ESI) listens on the TCP port associated with 1211 HTTPS (typically port 443) 1212 2. The client host initiates an HTTP request using a random unused source TCP port to the 1213 EndDevice resource’s server host using the TCP port associated with HTTPS 1214 3. If no TLS session is in place, a TLS handshake SHALL occur between the client host and server 1215 host: 1216 a. Authentication of the server host SHALL be done as part of the TLS handshake by 1217 validating its Device Certificate 1218 b. If the client host has a Device Certificate, authentication of the client host SHALL be 1219 done as part of the TLS handshake by validating the client host’s Device Certificate using 1220 the inherent PKI. If security policy dictates, additional validation such as OCSP MAY be 1221 required 1222 c. If the client host has a Self-signed Certificate, the Self-signed Certificate SHALL be 1223 validated for correctness. 1224 d. If the client host does not have a certificate and the security policy allows, client host 1225 authentication MAY NOT need to take place, or secondary client authentication MAY 1226 take place after the TLS handshake. 1227 4. Authorization then occurs whereby the ACLs of the server resources corresponding to the 1228 registering client host SHALL be set according to the security policy and the presence in 1229 aclRegistrationList. This ensures that following registration, a client host can typically proceed to 1230 access all the resources it is authorized to without having to perform any further procedures. 1231 5. The client host SHALL subsequently re-use its Device Certificate to authenticate with any other 1232 server host. It does not need to re-authenticate with the EndDevice resource’s server host.

Smart Energy Profile 2.0 Page 47 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1233 10 Discovery 1234 mDNS and DNS-SD are to be used as part of the Smart Energy Profile 2.0 for device discovery, resource 1235 discovery, and resolving hostnames. The following Section describes the parameters used with these 1236 protocols. 1237 For further information regarding mDNS and DNS-SD, see: 1238 http://datatracker.ietf.org/doc/draft-cheshire-dnsext-multicastdns/ 1239 http://datatracker.ietf.org/doc/draft-cheshire-dnsext-dns-sd/ 1240 http://tools.ietf.org/html/draft-lynn-dnsext-site-mdns-01 1241 Multicast DNS (mDNS) employs multicast addressing for requests and responses in support of resource 1242 discovery. IPv6 address scoping is used to define reachability including address types for Global 1243 addressing, Site-Local addressing and Link-Local addressing. The Smart Energy 2.0 application profile 1244 will use Site-Local address scope. 1245 mDNS requests and responses from HAN devices that are mains powered SHALL use site-local multicast 1246 addressing to ensure that all sub-networks within the HAN are in address scope. Guidelines on the use of 1247 unicast responses SHALL be employed as described in the mDNS draft. Battery operated devices in the HAN 1248 SHALL use site-local multicast addressing for mDNS requests and SHOULD request unicast 1249 responses. HAN devices making mDNS requests that generate responses specific to the requesting HAN 1250 device (e.g., requests such as those requesting ESI's where the particular HAN device is registered) SHALL 1251 employ site local multicast addresses and SHALL request unicast responses.

1252 10.1 Service Type

1253 The service type used with DNS-SD SHALL be “smartenergy” and has been registered appropriately 1254 with dns-sd.org (see http://www.dns-sd.org/ServiceTypes.html). 1255 Thus, a Service Instance Name example would be: 1256 Test\032Server._smartenergy._tcp.local.

1257 Where “Test Server” is the Service Name (described below) with the ‘space’ character encoded as 1258 required, “smartenergy” is the Service Type, “tcp” is the transport protocol, and “local” is the 1259 domain (in this case, we are utilizing mDNS).

1260 10.2 Sub-Types 1261 Sub-types are filters that correspond to the top level access points into a function set. For example, if a 1262 device such as an electricity meter also serves gas metering data via mirroring, that device will have two 1263 sub-type filters, one for metering and one for the ability to mirror metering data. Client devices can then 1264 further interrogate the device via the returned Device Capabilities URI to determine the URIs of the 1265 function set collections (Lists) that the device serves. Sub-types serve as filters only, they do not affect the 1266 response. Because these responses are multicast they are kept short and only contain the URI of the 1267 device's Device Capabilities resource.The following table includes the service sub-types and their 1268 corresponding SEP 2.0 function sets. 1269 Table 10-1: Service sub-types and their corresponding SEP 2.0 function sets. Sub-Type Device Capabilities Field Name SEP 2.0 Function Set dr DemandResponseProgramListLink Demand Response / Load Control

Smart Energy Profile 2.0 Page 48 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

upt UsagePointListLink Metering mup MirrorUsagePointListLink Metering msg MessagingProgramListLink Messaging tp TariffProfileListLink Pricing rsp ResponseListLink Response ppy PrepaymentListLink Prepayment der DERListLink Distributed Energy Resource (DER) Capability derc DERProgramListLink Distributed Energy Resource (DER) Control bill CustomerAccountListLink Billing edg EndDeviceGroupListLink End Device Group cfg ConfigurationLink Configuration lel LogEventListLink LogEvent Log file FileListLink Firmware Download netstat NetworkStatusLink Network Status tm TimeLink Time edev EndDeviceListLink End Device sub SubscriptionListLink Subscription dinfo DeviceInformationLink Device information pstat PowerStatusLink Power Status

1270 10.3 TXT Record 1271 This section defines the use of the TXT record defined in the DNS-SD specification. This application 1272 SHALL use a single TXT record. The following table contains other parameters that SHALL be included 1273 in the TXT record. 1274 Table 10-2: Other parameters that SHALL be included in the TXT record. Key=Value Example txtvers={#} txtvers=1 path={relative URI of DeviceCapabilities} path=/dcap description={human-readable name} description=Home Electricity Meter product={short product name/model} product=Foo 1000

1275 1276 txtvers SHALL be the first key in the TXT record. 1277 For this version of the Smart Energy Profile, the value of the txtvers key SHALL be 1. If it is found in a 1278 response to be other than 1 the TXT record SHALL be ignored.

Smart Energy Profile 2.0 Page 49 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1279 Unknown key pairs in a response SHALL be ignored. 1280 The path key SHALL provide the URI used to locate the device’s DeviceCapability resource 1281 and include the leading slash of the given path. 1282 The description and product keys SHALL be in UTF-8 format.

1283 10.4 Service Name 1284 A device SHALL assign itself a user-friendly service name of up to 63 bytes in UTF-8 format. Should a 1285 name conflict occur a device SHALL assign itself a new name until conflicts are resolved. A conflict 1286 SHOULD be resolved by appending a number to the name (for example, “Name(2)” for the first conflict, 1287 “Name(3)” for the second conflict, etc.). Device Discovery, Resource Discovery, and Gradual Reveal 1288 Walkthrough. 1289 This sub-section provides a walkthrough of the process a client would use to find a resource of interest 1290 using the appropriate portions of this specification. 1291 Link layer joining is not covered in this specification. Refer to the appropriate specification for details 1292 regarding joining the appropriate data link layer network. 1293 1294 The following sequence demonstrates the discovery process for a non-singleton resource where 1295 End Device Groups are not used. This sequence assumes some knowledge from either other 1296 specifications or sections later in this document so you may need to jump ahead and read those 1297 sections before this sequence is fully understood, 1298 1. Use DNS-SD to locate the servers with the function sets of interest (See DNS-SD specification) 1299 2. For each server do the following: 1300 a. Establish TLS session if required (see Security section). 1301 b. GET the Device Capabilities resource.(See Device Capability Section) 1302 c. Look for the desired resource in the Device Capabilities resource, 1303 d. If there is an entry in Device Capabilities it will contain a URI of a list of that resource. 1304 3. Determining which of the discovered resources are of interest depends on the resource and 1305 other outside factors. (e.g. If the resource is metering, then the meter of interest might be the 1306 one that has the Premises Aggrigation Point attribute set true.) 1307 1308 It should be noted that clients SHALL dynamically discover the URI(s) of the resource(s) of interest, as 1309 the URI(s) MAY vary from server to server and MAY occasionally vary over the lifetime of a given 1310 server. Clients SHALL rediscover URIs upon notification of the server DNS-SD record change or a 1311 request fails with a 404 (Notfound) error. Clients SHALL in the case of redirects, follow the guidance in 1312 the HTTP specification (RFC 2616). 1313 Devices SHALL NOT assume the use of the URIs and their structures given throughout this specification. 1314 All resources SHALL be self-describing as it is acknowledged that URIs, schemas, and resources MAY 1315 change in the future. All resources SHALL contain links to their subordinate resources to support 1316 flexibility in URIs and future extensibility. Thus, to allow for extensibility and granularity, all objects 1317 SHALL be described in schemas and referenced via URIs. The URIs presented throughout this 1318 specification SHOULD be regarded as RECOMMENDED. Thus, clients SHALL NOT assume that URIs 1319 for resources are fixed on all servers or even on a given server (over time), but rather retrieve the

Smart Energy Profile 2.0 Page 50 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1320 appropriate URIs through resource discovery and links within resources. For network efficiency, devices 1321 MAY assume URIs are fixed on a particular server over time. If this ever returns an unexpected result, 1322 then that device should perform resource discovery again.

Smart Energy Profile 2.0 Page 51 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1323 11 Support Resources

1324 11.1 Device Capabilities Function Set 1325 11.1.1 DeviceCapability Resource 1326 11.1.1.1 Overview 1327 The DeviceCapability resource enumerates the function sets supported by a device. 1328 Smart Energy 2 clients locate HAN services by performing DNS Service Discovery (DNS-SD) queries to 1329 the HAN. A query may be issued non-specifically for any Smart Energy 2 device, or a Smart Energy 2 1330 device supporting a specific function set. Successful DNS-SD queries SHALL return links to the 1331 matching device’s DeviceCapability resource. The client is then free to further access the function sets 1332 enumerated within the DeviceCapability resource. 1333 11.1.1.2 Dependencies 1334 There are no dependencies on other function sets. 1335 11.1.1.3 URI Structure 1336 Table 11-1: URI Structure Table for the DeviceCapability Resource.

URI Model element Purpose

PUT

GET

POST DELETE /dcap DeviceCapabilities Used to determine the resources M D E D available on a server.

1337 1338 11.1.1.3.1 URI Actions 1339 11.1.1.3.2 GET 1340 GET /dcap SHALL return an XML representation of the DeviceCapability resource, which SHALL be a 1341 valid XML instance per the XML described in schema [ZB 106049]. 1342 11.1.1.4 Subscription / Notification Behavior 1343 Subscription/ notification behavior is not supported. 1344 11.1.1.5 Page List Ordering 1345 This resource does not contain any lists so no page ordering is specified. 1346 11.1.1.6 Application Guidelines/Behavior 1347 This resource is read-only. 1348 Clients MAY query this resource to determine what resources are available. The resources a server 1349 exposes SHALL be determined by the access rights of the client on this server. For an alternative way to 1350 locate resources see the sections on End Device and End Device Group. 1351 A resource serving device SHALL implement the DeviceCapability resource. 1352 11.1.1.7 LogEvents Generated 1353 There are no LogEvents generated by this resource. 1354 11.1.1.8 Use of Parent Fields 1355 Device Capabilities

Smart Energy Profile 2.0 Page 52 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1356 Resource 1357 replyTo – SHALL NOT be used in this function set. 1358 ResponseRequired – SHALL NOT be used in this function set. 1359 signatureRequired – SHALL NOT be used in this function set. 1360 Subscribable – SHALL NOT be used in this function set. 1361 Identified Object 1362 Description – MAY contain a text description of this time object. 1363 mRID – SHALL NOT be used in this function set.

1364 11.2 End Device Resource (formerly EndDevice Resource) 1365 11.2.1 Overview 1366 The EndDevice resource provides interfaces to exchange information related to a particular client 1367 EndDevice. The major resources are listed below:

1368  EndDevice (edev) – Client Device 1369 EndDevice resource “edev” is hosted by a server providing resources. Resources associated with that 1370 device are provided as data and links to other resources. 1371 11.2.2 Dependencies 1372 EndDevice requires the following server resources be present: 1373 - Time function set (e.g., time, device information)

1374 11.2.3 URI Structure and Actions 1375 All valid URI structures are listed in the following table. The link to the EndDevice resource SHALL be 1376 made available through DeviceCapability, which is discovered using DNS-SD. 1377 All allowable operations (e.g., GET, PUT, POST, and DELETE) for clients for each URI are also listed. 1378 Sample XML payloads can be found in the subsequent Sections. 1379 11.2.3.1 URI Structures 1380 Table 11-2: URI Structure Table for EndDevice List. URI - Purpose GET PUT POST DELETE http{s}://{base} /edev EndDevice resource list. Devices M N/A O O implementing the /edev resource MAY (HAN (client to (client to support multiple instances of device post its remove EndDevice. not instance its allowed record) instance to record)

refresh

the list)

Smart Energy Profile 2.0 Page 53 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

/edev/{#} EndDevice instance including M O N/A O associated resource links (e.g., (to (cannot (to subscriptions, end device groups). request POST to remove a update an client) to a existing EndDe instance) vice)

/edev/{#}/dstat Allows clients to put their current O M O O operational state to a host.

/edev/{#}/rg Contains registrations related to the M O O O indicated device.

/edev/{#}/edg Contains end device groups related to M O M M the indicated device. Documented in

Section 11.3.

/edev/{#}/sub Contains subscriptions related to the M O M M indicated device. Documented in Section 9.

1381 M – Mandatory 1382 O – OPTIONAL 1383 N/A – Not applicable 1384 Each /edev server SHALL have a /edev resource containing resources for clients associated with it. 1385 11.2.3.2 URI Actions 1386 HTTP requests and responses exchanged between client and server are listed in the following Sections. 1387 11.2.3.3 EndDevice List 1388 Uses:

1389  To provide a list of EndDevices associated with a host, and provide links and information related 1390 to those devices. 1391 1392 The EndDevice List resource URI, obtained from DeviceCapability, is: 1393 http{s}://{host}

Smart Energy Profile 2.0 Page 54 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1394 1395 GET: 1396 GET /edev returns a list (described by the schema) of EndDevices, each with their own URI that is 1397 subordinate to this URI. If POST to /edev is not supported, then it is assumed that an out of band 1398 mechanism is used to associate the device with the server, and the device should check the list 1399 periodically to find its record, no less than once per day, and no more than once per hour, by looking 1400 for the record where the mRID is the identifier of the device.

1401 The client would send: 1402 GET /edev HTTP/1.1 1403 Host: {Base} 1404 1405 The server would respond: 1406 HTTP/1.1 200 OK 1407 Content-Type: application/xml 1408 Content-Length: 489 1409 1410 1411 1413 1414 86eb25a1 1415 Pool Pump 387 1416 10 1417 1418 1419 1420 1421 1422 1423 1424 POST: 1425 POST /edev creates a new EndDevice resource.

1426 The client would send: 1427 POST /edev HTTP/1.1 1428 Host: {Base} 1429 1430 1431 1432 86eb25a1 1433 Pool Pump 387 1434 10 1435 1436 1437 The server would respond: 1438 HTTP/1.1 201 OK 1439 Location: /edev/1 1440 1441 11.2.3.4 EndDevice Instance 1442 The EndDevice Instance resource URI is: 1443 http{s}://{Base}/edev/{#} 1444 1445 GET: 1446 GET /edev/{#} returns a single EndDevice resource. Note that the XML data below is example only.

Smart Energy Profile 2.0 Page 55 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1447 The client would send: 1448 GET /edev/1 HTTP/1.1 1449 Host: {Base} 1450 1451 The server would respond: 1452 HTTP/1.1 200 OK 1453 Content-Type: application/xml 1454 Content-Length: 366 1455 1456 1457 1458 86eb25a1 1459 Pool Pump 387 1460 10 1461 1462 1463 1464 1465 1466 1467 1468 11.2.3.5 EndDeviceStatus 1469 The EndDeviceStatus resource URI is: 1470 http{s}://{Base}/edev/{#}/dstat 1471 1472 This resource is constantly changing, and history of previous status records is not supported. Only 1473 one representation exists, so when it is updated, clients SHALL use PUT. 1474 PUT: 1475 PUT /edev/{#}/dstat allows clients to update a host with their current operational state.

1476 The client would send: 1477 PUT /edev/1/dstat HTTP/1.1 1478 Host: {Base} 1479 1480 1481 1482 6 1483 2 1484 12746729 1485 1486 -3 1487 1 1488 6 1489 22780 1490 1491 1325376000 1492 1493 1494 The server would respond: 1495 HTTP/1.1 204 OK 1496 Content-Type: application/xml

Smart Energy Profile 2.0 Page 56 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1497 11.3 EndDeviceGroupList 1498 11.3.1 Overview 1499 An end device group enrollment resource is provided to support assignment of devices into application 1500 groups to facilitate service provider operations. An end device group is solely defined by the service 1501 provider or a higher function device like a PEMS and can be based on a HAN asset class/category, 1502 service provider program, or any other criteria the service provider defines. A device can be a member of 1503 one or more end device groups. The assignment to an end device group is managed by the service 1504 provider or other authorized entity and MAY utilize access controls lists (ACLs). 1505 11.3.2 Dependencies 1506 There are no dependencies on other function sets other than Base. However, use of End Device Groups 1507 generally requires at least one other function set be implemented in order to be useful. 1508 11.3.3 Sequence Diagrams 1509 There are no complex operations requiring sequence diagrams. 1510 11.3.4 URI Structure and Actions 1511 11.3.4.1 URI Structure 1512 Table 11-3: URI Structure Table for End Device Groups. URI – Assume all URIs Purpose GET PUT POS DELET begin with T E “http(s)://{Host1}” /edev Highest level list of devices with end O O O O device group assignments. /edev/{#}/edg Location for an individual device’s end M O O O device group assignment(s). Returns the list of all EndDeviceGroups assigned to the device. /edg List of all EndDeviceGroups present in a M O O O particular namespace. /edg/{#} Specific EndDeviceGroup instance. M O O O Contains details about the EndDeviceGroup as well as links to the specific function set instances applicable to the EndDeviceGroup. /edg/{#}/{fn} URI for a particular function set that is a M O O O constituent of the EDG instance, where “fn” is a generic placeholder for a function set resource.

1513 1514 11.3.4.2 URI Actions 1515 1516 Issuing a GET to the /edev/{#}/edg URI returns a list of EndDeviceGroups assigned to the device.

1517 The client would send: 1518 GET /edev/{#}/edg/ HTTP/1.1 1519 Host: {Host1}

Smart Energy Profile 2.0 Page 57 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1520 1521 The server would respond: 1522 HTTP/1.1 200 OK 1523 Content-Type: application/xml 1524 1525 1526 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 11.3.5 Subscription / Notification Behavior 1541 It is RECOMMENDED that clients subscribe to the following URIs:

1542  /edev/{#}/edg/, where the EUI-64 is an unique identifier for the client

1543  each /edg/{#}, where {#} represents the specific end device group memberships of the device

1544 11.3.6 Application Guidelines / Behavior 1545 11.3.6.1 /edev 1546 The registration server SHALL create a new instance in the /edev/ list at any time before or upon 1547 authentication of the device. The service provider MAY configure the server to automatically assign 1548 EndDeviceGroups (under /edev/{#}/edg/) per its business policies. For example, service providers may 1549 have certain default EndDeviceGroups to which they will post messages applicable to all HAN devices 1550 (e.g., public service announcements, public pricing, emergency communications). Service providers may 1551 also update the entries for devices as necessary to support HAN operations. The methods for doing this 1552 are out of scope for this document. 1553 1554 11.3.6.2 /edev/{#}/edg 1555 A Client device SHALL issue an initial GET to its EndDevice resource instance on the server to discover 1556 its EndDeviceGroup assignments upon application authentication. This returns a list of EndDeviceGroup 1557 assignments to which the client belongs and provides the client with the information it needs to quickly 1558 learn of new communications in the various function set servers of interest to it. If the /edev/{#}/ resource 1559 does not exist for a client, that client SHALL perform service discovery using DNS-SD to discover what 1560 services in the HAN are available to it. Please refer to Section 11.2 for further guidelines if the /edev/{#} 1561 resource does not exist for a client. 1562 If a client does not subscribe to its /edev/{#}/edg/ URI, then it SHALL periodically check its URI not 1563 more than once per hour and no less than once every 24 hours. 1564 If a server supports EndDeviceGroupList, it SHALL support a minimum of 1 EndDeviceGroupList server 1565 for each HANHAN device. A server SHOULD support 3 EndDeviceGroupList servers for each 1566 HANHAN device.

Smart Energy Profile 2.0 Page 58 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1567 11.3.6.3 EndDeviceGroup 1568 EndDeviceGroups is the container for EndDeviceGroup instances present in the HAN/PAN.HAN. 1569 Service providers or Home Energy Management Systems can use an EndDeviceGroup to associate a 1570 grouping of function sets for a specific need per their operational mandates. The EndDeviceGroup 1571 instance is a simple mechanism for quickly learning about the function sets that apply to a particular 1572 client. Clients identify which EndDeviceGroups apply to them by querying their EndDeviceGroups 1573 resource (/edev/{#}/edg) under the End Device resource. It is possible for a device to be assigned 1574 multiple EndDeviceGroups. 1575 Each EndDeviceGroup contains a collection of URIs identifying the resources that apply to this group. It 1576 is expected that clients periodically poll their group assignments or subscribe to them to monitor for 1577 changes in their assignments and/or the member function sets of their assigned EndDeviceGroups. If a 1578 client does not subscribe to its EndDeviceGroup assignments, then it SHALL periodically query the 1579 server for updates. Clients devices SHALL query at least once every 24 hours but not more than once per 1580 hour. 1581 11.3.6.3.1 Description 1582 Provides service provider with the ability to apply a description to a particular EndDeviceGroup instance 1583 (e.g., “Summer Discount Program”). 1584 11.3.6.4 Guidelines for Sleepy Devices 1585 Sleepy end devices SHALL obtain updated end device group membership information by querying the 1586 appropriate URI (/edev/{#}/edg/) at least once every 24 hours but not more than once per hour.

Smart Energy Profile 2.0 Page 59 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1587 11.4 Subscription / Push Mechanism 1588 11.4.1 Overview 1589 This Section describes the design and use of resources that support a generic, lightweight 1590 subscription/push mechanism for use throughout the specification. This mechanism may be useful when 1591 a host wishes to quickly learn of changes to a resource on another host. 1592 The following text further clarifies the roles of the subscribe and push resources. 1593 11.4.2 Subscription Resource 1594 A subscription resource is realized as a resource for an individual client EndDevice, providing interfaces 1595 to all subscriptions for the given client EndDevice. 1596 An example subscription resource URI is: 1597 http{s}://{host1}/edev/{#}/sub

1598 /edev/{#}/sub is a list of subscriptions for a given client whose details are at the address /edev/{#}. 1599 11.4.2.1 GET 1600 GET /edev/{#}/sub returns a list (described by the schema and subject to security permissions) of 1601 resources to which the client described at the address /edev/{#} is subscribed and the client’s associated 1602 response address.

1603 In the following example, {host1}refers to the host on which the subscription resource resides and 1604 {host2}refers to the host subscribing to specific resources and on which the push resource resides.

1605 The client would send: 1606 GET /edev/{#}/sub HTTP/1.1 1607 Host: {host1} 1608 1609 The server would respond: 1610 HTTP/1.1 200 OK 1611 Content-Type: application/xml 1612 Content-Length: {length} 1613 1614 1615 1616 1617 /resource1 1618 http{s}://{host2}/push 1619 1620 1621 /resource5 1622 http{s}://{host2}/push 1623 1624 1625 11.4.2.2 PUT 1626 PUT /edev/{#}/sub replaces the list (described by the schema and subject to security permissions) of 1627 resources to which the client described at the address /edev/{#} is subscribed, or creates the list at this 1628 URI if one does not already exist.

Smart Energy Profile 2.0 Page 60 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1629 In the following example, {host1} refers to the host on which the subscription resource resides and 1630 {host2} refers to the host subscribing to specific resources and on which the push resource resides.

1631 The client would send: 1632 PUT /edev/{#}/sub HTTP/1.1 1633 Host: {host1} 1634 Content-Type: application/xml 1635 Content-Length: {length} 1636 1637 1638 1639 1640 /resource2 1641 http{s}://{host2}/push 1642 1643 1644 /resource7 1645 http{s}://{host2}/push 1646 1647 1648 1649 The server would respond (if the resource were newly created): 1650 HTTP/1.1 201 Created 1651 Location: /edev/{#}/sub 1652 1653 OR 1654 The server would respond (if the resource already existed and was modified): 1655 HTTP/1.1 204 No Content 1656 11.4.2.3 POST 1657 POST /edev/{#}/sub appends to the list (described by the schema and subject to security permissions) 1658 of resources to which the client described at the address /edev/{#} is subscribed, or creates the list at 1659 this URI if one does not already exist.

1660 In the following example, {host1}refers to the host on which the subscription resource resides and 1661 {host2}refers to the host subscribing to specific resources and on which the push resource resides.

1662 The client would send: 1663 POST /edev/{#}/sub HTTP/1.1 1664 Host: {host1} 1665 Content-Type: application/xml 1666 Content-Length: {length} 1667 1668 1669 1670 1671 http{s}://{host1}/resource2 1672 http{s}://{host2}/push 1673 1674 1675 http{s}://{host1}/resource7 1676 http{s}://{host2}/push 1677 1678 1679 1680 The server would respond (if the resource were newly created):

Smart Energy Profile 2.0 Page 61 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1681 HTTP/1.1 201 Created 1682 Location: /edev/{#}/sub 1683 1684 OR 1685 The server would respond (if the resource already existed and was appended): 1686 HTTP/1.1 204 No Content 1687 11.4.2.4 DELETE 1688 DELETE /edev/{#}/sub deletes the list (described by the schema and subject to security permissions) 1689 of resources to which the client described at the address /edev/{#} is subscribed.

1690 In the following example, {host1} refers to the host on which the subscription resource resides and 1691 {host2} refers to the host subscribing to specific resources and on which the push resource resides.

1692 The client would send: 1693 DELETE /edev/{#}/sub HTTP/1.1 1694 Host: {host1} 1695 1696 The server would respond: 1697 HTTP/1.1 204 No Content 1698 11.4.3 Push Resource 1699 The push resource is used to receive notifications that a resource to which a host is subscribed has 1700 changed. The location of the push resource is passed to the subscription server in the body of the 1701 subscription.

1702 When {host1} wishes to notify {host2} that a resource on {host1} to which {host2} has subscribed 1703 has changed, {host1} will POST a notification as follows: 1704 POST /push HTTP/1.1 1705 Host: {host2} 1706 Content-Type: application/xml 1707 Content-Length: {length} 1708 1709 1710 1711 http{s}://{host1}/resource4 1712 http{s}://{host1}/edev/{#}/sub 1713 <{Type of resource4}> 1714 {Representation of resource4} 1715 1716 1717 11.4.4 Conditional Subscription / Report by Exception 1718 If allowed by the specific function set, some resources (those containing a numeric value only) can have 1719 conditional subscriptions to enable a report by exception capability. The following conditions are 1720 allowed and are specified in the subscription:

1721  Lower Threshold – used to cause a notification when the resource’s value is below the given 1722 value.

1723  Upper Threshold – used to cause a notification when the resource’s value is above the given 1724 value. 1725 Note, both an upper threshold and a lower threshold may be specified for a given subscription.

Smart Energy Profile 2.0 Page 62 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1726 If neither a lower threshold nor an upper threshold is specified, then a server SHALL send a notification 1727 whenever the resource to which the client is subscribed changes (including a subordinate item being 1728 removed from a list resource). If a lower threshold and/or an upper threshold are specified, then a server 1729 SHALL send a notification whenever the appropriate value crosses the appropriate threshold for the 1730 resource to which the client is subscribed.

1731 As an example, imagine a resource located at http{s}://{host1}/resource with the following 1732 representation: 1733 1734 5 1735 FFFF 1736 On 1737 1738 A valid conditional subscription, specifying both an upper and lower threshold could be the following: 1739 1740 1741 1742 http{s}://{host1}/resource 1743 http{s}://{host2}/push 1744 1745 1746 3 1747 1748 1749 1750 1751 7 1752 1753 1754 1755 1756 11.4.5 Subscriptions with Limited Notifications 1757 This sub-section presents some special considerations and elements that apply to subscriptions to allow 1758 subscribers to limit the amount of data returned in a notification (if allowed by the appropriate function 1759 set and subject to security permissions). 1760 The following element SHOULD be specified in the object:

1761  limit – this element, when present, is used to indicate the maximum number of items that should 1762 be included in a notification when the resource changes. This element is meant to be functionally 1763 equivalent to the ‘limit’ query string parameter, but applies to both list resources as well as other 1764 resources. For list resources, if a limit of ‘0’ is specified, then notifications SHALL contain a list 1765 resource with results=’0’ (equivalent to a simple change notification). For list resources, if a limit 1766 greater than ‘0’ is specified, then notifications SHALL contain a list resource with results equal to 1767 the limit specified (or less, should the list contain fewer items than the limit specified). For non- 1768 list resources, if a limit of ‘0’ is specified, then notifications SHALL NOT contain a resource 1769 representation (equivalent to a simple change notification). For non-list resources, if a limit 1770 greater than ‘0’ is specified, then notifications SHALL contain the representation of the changed 1771 resource. 1772 Query string parameters SHALL NOT be specified when subscribing to list resources. 1773 If a limit element is not specified, notifications SHALL use a default limit of ‘1’.

Smart Energy Profile 2.0 Page 63 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1774 As an example, imagine a list resource located at http{s}://{host1}/list with the following representation: 1775 1776 1777 A 1778 1779 1780 B 1781 1782 1783 C 1784 1785 1786 1787 A valid subscription, specifying a limit of ‘1’ could be the following: 1788 1789 1790 http{s}://{host1}/list 1791 1 1792 http{s}://{host2}/push 1793 1794 1795 1796 A valid notification could be the following: 1797 1798 http{s}://{host1}/list 1799 http{s}://{host1}/edev/{#}/sub 1800 1801 1802 A 1803 1804 1805 1806 1807 11.4.6 Subscription Rules 1808 A subscription renewal is a subscription to the same resource from the same client, regardless of 1809 subscription parameters.

1810  [Sub-A]: Clients SHALL send subscription renewals every 24 hours, and no more often than 1811 every 1 hour. 1812  [Sub-B]: Servers MAY remove subscriptions at any time. 1813  [Sub-C]: Servers SHOULD remove subscriptions if a client has not renewed in 36 hours. 1814  [Sub-D]: Subscriptions SHALL be maintained on servers through power loss. 1815  [Sub-E]: Servers SHALL use the subscription parameters from the latest subscription renewal. 1816  [Sub-F]: If the transport delivery of a subscription notification fails, servers SHALL attempt to 1817 re-deliver the notification, retrying using the backoff mechanism specified in XXX with 1818 parameters YYY. Servers SHALL continue retrying until:

1819 a) the subscription notification succeeds, or 1820 b) the subscription times out as described in [Sub-C], or 1821 c) a new subscription notification for the same resource is sent, (e.g., resource has new 1822 value(s), in which case the increasing back off timer would be reset).

Smart Energy Profile 2.0 Page 64 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1823  [Sub-G]: If the URI of a resource changes, then subscriptions to that resource SHALL be 1824 terminated. 1825  [Sub-H]: For subscriptions to non-list resources, a notification SHALL be sent whenever the 1826 representation of the non-list resource changes. 1827  [Sub-I]: For subscriptions to list resources, a notification SHALL be sent whenever any 1828 subordinate resources are added to or removed from the list, or if the representation of those 1829 subordinate resources change. See Section 6.7 for more information. 1830  [Sub-J]: To prevent overwhelming network resources, notifications SHALL be sent to a given 1831 client no more than once every 30 seconds. 1832  [Sub-K]: Servers implementing the subscription resource SHALL be capable of maintaining a 1833 minimum of 1 subscription. 1834  [Sub-L]: If a server implementing the subscription resource is unable to accept a subscription, the 1835 server SHALL return an HTTP 5xx error. 1836  [Sub-M]: When a server removes or terminates a subscription, it SHALL send the client a 1837 terminate subscription. The server SHALL send a Notification to the client’s “Post URI” for the 1838 affected subscription. The Resource contained in the Notification SHALL be a Subscription, 1839 containing a Status element identifying the reason for terminating the subscription. When a 1840 subscription is terminated because the subscribed resource has moved, servers MAY include 1841 newResourceURI in the subscription termination message, indicating the resource’s new location.

1842  [Sub-N]: If a client receives a notification for a subscription of which it is unaware, the client 1843 SHALL return an HTTP 5xx error.

Smart Energy Profile 2.0 Page 65 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1844 11.5 Response 1845 TBD 1846 1847 1848

Smart Energy Profile 2.0 Page 66 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1849 12 Common Resources

1850 12.1 Time Function Set 1851 12.1.1 Time Resource 1852 12.1.1.1 Overview 1853 HAN devices synchronize their time source by locating and acquiring time from a Time resource. Time 1854 synchronization of HAN devices is REQUIRED to effectively support DRLC, pricing changes, time 1855 stamping of metering data, etc. 1856 Devices implementing the Time resource obtain correct time either directly from an external authoritative 1857 time source (e.g. NTP) or indirectly from an inaccurate source (e.g., manually entered via UI). 1858 For rules regarding the processing of events from multiple servers, please refer to Section 13.1.5.3 1859 12.1.1.2 Dependencies 1860 Servers of this function set require the support of the Configuration function set. 1861 There may be a dependency upon an external time source for UTC time (NTP service, etc). 1862 12.1.1.3 URI Structure 1863 Table 12-1: URI Structure Table for the Time Resource.

URI Model element Purpose

PUT

GET

POST DELETE

/tm Time URI for a Time Resource. M O E D

1864 1865 12.1.1.3.1 URI Actions 1866 12.1.1.3.2 GET 1867 GET /tm SHALL return an XML representation of the Time resource, which SHALL be a valid XML 1868 instance per the XML described in schema [ZB 106049]. 1869 12.1.1.4 Subscription / Notification Behavior 1870 Subscription / notification behavior is not supported (time values are constantly changing). 1871 12.1.2 Page List Ordering 1872 This function set does not contain any lists so no paging is supported. 1873 12.1.2.1 Application Guidelines / Behavior 1874 All devices SHALL implement the time resource as a client or a server or both. 1875 All communication of time used throughout the specification, with the exception of time for user display, 1876 SHALL be UTC. Devices with user displays SHALL support local time and daylight savings time offsets 1877 to UTC.

Smart Energy Profile 2.0 Page 67 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1878 A Time server MAY be specified through End Device Group. If a device is assigned multiple 1879 EndDeviceGroups and they specify different time sources the device SHALL execute the events from that 1880 group relative to the specified time source of that group. 1881 If a device is directed through End Device Groups to use a specific time source it SHALL use that time 1882 source. If it is not specified in an End Device Group then it SHALL use the time source from the device 1883 that is serving the events being acted on. If it is not acting on events it SHALL choose the time source 1884 with the best quality metric. 1885 If a device displays time then it SHOULD display the time with the highest quality metric. 1886 If a time server serves an uncoordinated time in the UTC time field it SHALL have a quality metric of 7 - 1887 time intentionally uncoordinated. 1888 See the XML schema described in schema [ZB 106049] for details of the quality metric. 1889 Devices SHOULD periodically query the Time service and compare the response with the local device 1890 time to determine local clock accuracy. 1891 A device SHOULD manage the frequency of its Time resource updates and subsequent local clock 1892 updates to provide local time accurate to within: 1893 1. 10 seconds per 24 hour period for devices displaying time to the user 1894 2. 60 seconds per 24 hour period if there is no user interface. 1895 To maintain time synchronization, HAN devices SHALL maintain these accuracies via Time resource 1896 requests. To keep network traffic to a minimum this polling SHALL be no more than once per 15 minutes 1897 once a valid time source has been established. Requests SHALL NOT exceed once per 15 seconds and 1898 SHALL employ exponential back off prior to establishing a valid time source. These requirements apply 1899 on a per time server basis. 1900 If a HAN device has a clock that is not set, it MAY need to find a Time resource and obtain time before 1901 going into service. It MAY require an update from a Time resource with an authorative source 1902 (quality = 3) before going into service. 1903 This resource is read only. Time related configuration is handled within the Configuration resource. 1904 12.1.2.2 LogEvents Generated 1905 There are no LogEvents generated by this resource. 1906 12.1.2.3 Use of Parent Fields 1907 Time 1908 Resource 1909 replyTo – SHALL NOT be used in this function set. 1910 ResponseRequired – SHALL NOT be used in this function set. 1911 signatureRequired – SHALL NOT be used in this function set. 1912 Subscribable – This resource supports subscription. This field SHALL be set true if a 1913 given instance can be subscribed to. 1914 Identified Object

Smart Energy Profile 2.0 Page 68 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1915 Description – SHALL NOT be used in this function set. 1916 mRID – SHALL NOT be used in this function set. 1917

1918 12.2 DeviceInformation Function Set 1919 12.2.1 Device Information Resource 1920 12.2.1.1 Overview 1921 The DeviceInformation function set provides static manufacturer specific information about a device. 1922 12.2.1.2 Dependencies 1923 There are no dependencies on other function sets. 1924 12.2.1.3 Sequence Diagrams 1925 Not applicable. 1926 12.2.1.4 URI Structure 1927 Table 12-2: URI Structure Table for the DeviceInformation Resource.

URI Model Element Purpose

GET PUT POST DELETE /dinfo DeviceInformation URI for Device Information M D E D

1928 12.2.1.4.1 URI Actions 1929 12.2.1.4.2 GET 1930 GET /dinfo SHALL return an XML representation of the DeviceInformation resource, which SHALL be 1931 a valid XML instance per the XML schema described in schema [ZB 106049]. 1932 12.2.1.5 Subscription / Notification Behavior 1933 Subscription/ notification behavior is not supported. 1934 12.2.1.6 Page List Ordering 1935 There are no lists in this resource so no ordering is needed. 1936 12.2.1.7 Application Guidelines / Behaviors 1937 The DeviceInformation function set is used to provide information about the actual device. Any device 1938 that implements a HTTP server to serve resources SHALL implement the DeviceInformation resource. 1939 Client devices that do not implement a HTTP server are not required to serve the DeviceInformation 1940 function set. 1941 12.2.1.8 LogEvents Generated 1942 No LogEvents are generated by this resource 1943 12.2.1.9 Use of Parent Fields 1944 Device Information

Smart Energy Profile 2.0 Page 69 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1945 Resource 1946 replyTo – SHALL NOT be used in this function set. 1947 ResponseRequired – SHALL NOT be used in this function set. 1948 signatureRequired – SHALL NOT be used in this function set. 1949 Subscribable – SHALL NOT be used in this function set. 1950

1951 12.3 Power Status 1952 12.3.1.1 Overview 1953 The PowerStatus resource provides information regarding a device’s current power source, as well as 1954 basic status regarding any battery installed within the device. 1955 Implementation of this resource SHALL be OPTIONAL. 1956 12.3.1.2 Dependencies 1957 PowerStatus resource MAY post LogEvents to the LogEvent Log resource. 1958 12.3.1.3 Sequence Diagrams 1959 Not applicable. 1960 12.3.1.4 URI Structure 1961 Table 12-3: URI Structure Table for the PowerStatus Resource. URI Allowed Methods /pwrstat Resource URI GET PUT POST DELETE X

1962 12.3.1.4.1 URI Actions 1963 12.3.1.4.2 GET 1964 GET /pwrstat SHALL return an XML representation of the PowerStatus resource, which SHALL be a 1965 valid XML instance per the XML schema described in TBD.

1966 The client would send: 1967 GET /pwrstat HTTP/1.1 1968 Host: {host} 1969 The server would respond: 1970 HTTP/1.1 200 OK 1971 Content-Type: application/xml 1972 1973 1974 1975 214748364 1976 1 1977 1 1978 50

Smart Energy Profile 2.0 Page 70 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

1979 43200 1980 86400 1981 1982 12.3.1.5 Subscription / Notification Behavior 1983 Subscription/ notification behavior is not supported. 1984 12.3.1.6 Application Guidelines / Behavior 1985 The content of this resource will change as the device switches power sources (mains to battery, battery to 1986 mains) and as the battery charges/discharges. 1987 12.3.1.7 LogEvents Generated 1988 LE_LOW_BATTERY is posted to the LogEvent Log resource when the installed battery charge drops 1989 below the configured low battery charge threshold.

1990 12.4 NetworkStatus 1991 12.4.1.1 Overview 1992 The NetworkStatus resource provides information regarding the device’s network (IP) layer performance. 1993 Implementation of this resource SHALL be OPTIONAL. 1994 12.4.1.2 Dependencies 1995 There are no dependencies on other resources. 1996 12.4.1.3 Sequence Diagrams 1997 Not applicable. 1998 12.4.1.4 URI Structure 1999 Table 12-4: URI Structure Table for the NetworkStatus Resource. URI Allowed Methods /netstat Resource URI GET PUT POST DELETE X

2000 12.4.1.4.1 URI Actions 2001 12.4.1.4.2 GET 2002 GET /netstat SHALL return an XML representation of the NetworkStatus resource, which SHALL be a 2003 valid XML instance per the XML schema described in TBD. 2004 The client would send: 2005 GET /netstat HTTP/1.1 2006 Host: {host} 2007 The server would respond: 2008 HTTP/1.1 200 OK 2009 Content-Type: application/xml 2010 2011 2012

Smart Energy Profile 2.0 Page 71 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2013 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 2014 2015 2016 12.4.1.5 Subscription / Notification Behavior 2017 Subscription / notification behavior is not supported. 2018 12.4.1.6 Application Guidelines / Behavior 2019 The content of this resource will change as the device’s network (IP) layer processes incoming and 2020 outgoing packets. 2021 12.4.1.7 LogEvents Generated 2022 No LogEvents are generated by this resource.

2023 12.5 LogEvent Log 2024 12.5.1.1 Overview 2025 The LogEvent Log contains a list of time-stamped instances of LogEvents generated by the device. 2026 LogEvents are typically asynchronously generated warnings of some out of bounds condition or unusual 2027 significant event detected by the device. For example, the device’s battery charge falling below an 2028 operator designated low charge threshold, etc. 2029 The number of LogEvents supported within the LogEvent Log SHALL be vendor dependent. When a 2030 new LogEvent is raised, it SHALL be added as the first entry in the LogEvent Log. If the log is full, the 2031 oldest LogEvent SHALL be removed to make room for the latest incoming LogEvent. 2032 12.5.1.2 LogEvents 2033 A LogEvent SHALL be either Zigbee Alliance defined or vendor defined. A LogEvent SHALL be 2034 defined as follows:

2035  createdDateTime – The date and time that the event occurred.

2036  functionSet - If the vendorDefined flag is false, the functionSet is defined by the Zigbee Alliance 2037 and SHALL be one of the values from the table below (Smart Energy Profile 2.0 function set 2038 identifiers). If the vendorDefined flag is true, the functionSet is defined by the vendor. 2039 0 General (not specific to a function set) 1 Publish and Subscribe 2 End Device 3 End Device Groups 4 Response 5 Demand Response and Load Control 6 Metering 7 Pricing

Smart Energy Profile 2.0 Page 72 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

8 Messaging 9 Billing 10 Prepayment 11 Distributed Energy Resources 12 Time 13 Software Download 14 Device Information 15 Power Status 16 Network Status 17 LogEvent Log 18 Configuration 19- Reserved 255

2040

2041  logEventCode - A 16 bit unsigned integer. logEventCodes are scoped to a function set. If the 2042 vendorDefined flag is false, the logEventCode is defined by the Zigbee Alliance within one of the 2043 function sets of Smart Energy Profile 2.0. If the vendorDefined flag is true, the logEventCode is 2044 defined by the vendor.

2045  logEventPEN - 32 bit unsigned integer. The Private Enterprise Number(PEN) of the issuer of 2046 the logEvent. Zigbee assigned logEventCodes use the Zigbee Alliance PEN, which SHALL be 2047 included. Vendor assigned logEventCodes SHALL be accompanied with the vendor’s PEN, and 2048 SHALL be unique within a specific PEN (managed by the manufacturer). If the product includes 2049 libraries or sub-systems from another vendor, and the LogEvent is generated from one of these 2050 libraries or sub-systems, the PEN SHALL be the vendor PEN of the originating manufacturer.

2051  vendorDefined – A boolean value indicating, if true, that this event code is defined by a vendor 2052 and not the ZigBee Alliance. If this field is not present it SHALL be assumed to be false. 2053 12.5.1.3 Dependencies 2054 LogEvents SHALL be time stamped when they are added to the LogEventLog. The device therefore 2055 needs a time source, and should be using the highest quality Time resource it can obtain from the HAN. 2056 12.5.1.4 Sequence Diagrams 2057 Not applicable. 2058 12.5.1.5 URI Structure 2059 Table 13-5: URI Structure Table for the LogEventLog Resource. URI Allowed Methods /base/lel The LogEventList maintained on the device.

Smart Energy Profile 2.0 Page 73 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

GET PUT POST DELETE M NA NA O /base/lel/{#} A specific LogEvent entry from the LogEventList. Position 0 is the latest entry in the list. GET PUT POST DELETE M NA NA O

2060 12.5.1.5.1 URI Actions 2061 12.5.1.5.2 GET 2062 GET /lel SHALL return the designated number of entries from the LogEventList, which SHALL be a 2063 valid XML instance per the XML schema described in section TBD. GET SHALL implement the 2064 standard Smart Energy 2 list access idioms defined in section TBD.

2065 The client would send: 2066 GET /base/lel HTTP/1.1 2067 Host: {host} 2068 2069 The server would respond: 2070 2071 HTTP/1.1 200 OK 2072 Content-Type: application/xml 2073 2074 2075 2076 2077 214762733 2078 0x01 2079 0x0001 2080 0x00000001 2081 2082 2083 214762734 2084 0x02 2085 0x0002> 2086 0x00000001 2087 2088 2089 214762740 2090 0x00 2091 0x0001 2092 0x12340001 2093 true 2094 2095 2096 2097 2098 GET /lel/{#} SHALL return the specifically designated LogEvent from the LogEventList. The returned 2099 LogEvent SHALL be a valid XML instance per the XML schema described in Section TBD.

2100 The client would send: 2101 GET /base/lel/A HTTP/1.1 2102 Host: {host}

Smart Energy Profile 2.0 Page 74 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2103 2104 The server would respond: 2105 HTTP/1.1 200 OK 2106 Content-Type: application/xml 2107 2108 2109 2158 2160 en-US 2161 2162 214748364 2163 20 2164 2165 2166 30 2167 0 2168 30 2169 0 2170 2171 2172 MyDevice 2173 2174 2175 12.6.1.4.3 PUT 2176 PUT /cfg SHALL either create a new instance or modify the existing instance of the Configuration 2177 resource on the device. The Configuration resource contained in the PUT SHALL be a valid XML 2178 instance per the XML schema described in TBD. 2179 Depicted below is a partial update of a device’s Configuration resource. PUT of a Configuration resource 2180 SHALL be atomic. The entire set of configuration changes SHALL be accepted or rejected as a whole. 2181 The client would send: 2182 PUT /cfg HTTP/1.1 2183 Host: {host} 2184 2185 2186 2188 en-US 2189 2190 214748364 2191 2192 2193 The server would respond: 2194 HTTP/1.1 200 OK 2195 12.6.1.5 Subscription / Notification Behavior 2196 Subscription/ notification behavior is not supported. 2197 12.6.1.6 Application Guidelines / Behavior 2198 A device’s ability to persist configuration state through periods of power loss is not within scope of this 2199 specification. Devices which do not provide configuration persistence may be REQUIRED, at power up, 2200 to pull their configuration from some external source. 2201 12.6.1.7 LogEvents Generated 2202 No LogEvents are generated by this resource.

Smart Energy Profile 2.0 Page 77 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2203 12.7 Software Download Function Set 2204 12.7.1 Overview 2205 This Section describes the mechanisms used to support secure, interoperable, remote software download 2206 to Smart Energy 2.0 devices. It may also be used for remote download of other file artifacts such as log 2207 files, configuration files, security credential files, etc. 2208 There are two primary actors involved in a file download: the Loading Device (LD) and the File Service 2209 (FS). A LD polled model SHALL be supported, driven by the need to support sleeping devices. 2210 This specification designates files resident on the LD as activated or non-activated. A non-activated file 2211 is a file that has been physically loaded onto the LD, but not yet placed into operation. An activated file 2212 is a file that has been both physically loaded onto the LD and placed into operation. An example use of 2213 the activation state is the scenario in which an operator first must load and confirm load of new software 2214 images to a large set of devices (as non-activated, not running) before setting that software image to an 2215 activated state (the running image). 2216 A LD SHALL provide the ability to fully receive and store a non-activated file while the current activated 2217 file remains operational. For example, an LD SHALL be able to load a new software image (a non- 2218 activated file) while the current software image executes. In the case of a software image, the activated 2219 file is the running image. 2220 Public key cryptography SHALL be used to ensure integrity and provide source authentication of 2221 downloaded files. A manufacturer SHALL digitally sign files with the manufacturer’s signer private key. 2222 The LD SHALL verify the file signature using the manufacturer’s signer public key from the 2223 manufacturer’s signer certificate. 2224 LDs MAY be preinstalled with a manufacturer signer certificate. 2225 LDs MAY download the manufacturer signer certificate using the secure download operations described 2226 in this Section. 2227 Manufacturer signer root certificate SHALL be preinstalled on the LD. 2228 See Section 12 for discussion of Smart Energy 2 certificate chains and certificate formats. 2229 LD and FS SHALL support point to point distribution of files. Multicast distribution of files is not 2230 RECOMMENDED due to potential security vulnerabilities. 2231 12.7.2 File Format 2232 The Smart Energy 2.0 file format differs from that used in the ZigBee Over-the-Air Upgrading Cluster 2233 [ZB 095264], as there are details within the OTA file format that are not suitable for a PHY/MAC 2234 agnostic Smart Energy 2.0. 2235 Smart Energy 2.0 reduces file header content while making more extensive use of the sub-element idiom. 2236 Unless noted otherwise, all multi octet integer values SHALL be encoded in network byte order (big 2237 endian). 2238 12.7.2.1 General Structure 2239 The file format SHALL consist of a fixed size header followed by a variable number of sub-elements.

2240 Table 12-8: Sample File.

Smart Energy Profile 2.0 Page 78 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

Octets Fixed Variable Variable Variable

Data Header Upgrade File Signer Signature sub- sub-element Certificate sub- element element

2241 2242 12.7.2.2 Header Format 2243 All fields SHALL be mandatory. 2244 Table 12-9: Header Fields.

Octets Data Types Field Names

4 Unsigned Upgrade file identifier 32-bit integer

2 Unsigned Header version 16-bit integer

2 Unsigned Header length 16-bit integer

4 Unsigned Manufacturer PEN 32-bit integer

2 Unsigned File type 16-bit integer

4 Unsigned File version 32-bit integer

32 Character string Header string

4 Unsigned Total File size 32-bit integer (including header)

2245 The first entry of the table SHALL represent the first field in the header, and the last entry SHALL 2246 represent the last field. 2247 12.7.2.2.1 Upgrade File Identifier 2248 This is a unique 4-octet value that SHALL be included at the beginning of all upgrade files to support 2249 quick identification as an upgrade file. The value SHALL be “0x0BEEF11F”.

Smart Energy Profile 2.0 Page 79 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2250 12.7.2.2.2 Header Version 2251 The value SHALL be composed of a major and minor version number (one octet each). The high octet 2252 (or the most significant octet) represents the major version and the low octet (or the least significant octet) 2253 represents the minor version number. A change to the minor version means the upgrade file format is still 2254 backward compatible, while a change to the major version suggests incompatibility. 2255 The header version SHALL be 0x0200: major version of “02” and minor version of “00”. Note it is 2256 assumed that an OTA file contains a major version of “01”. 2257 12.7.2.2.3 Header Length 2258 This value SHALL be set to the full length of the header in octets, all fields inclusive. 2259 The value insulates existing software against new fields that may be appended to the header. If newly 2260 appended header fields are not compatible with current running software, the implementation SHALL 2261 process all fields understood and SHALL skip over any remaining octets in the header. 2262 12.7.2.2.4 Manufacturer PEN 2263 This is the IANA assigned Private Enterprise Number of the manufacturer. Value 0xFFFFFFFF SHALL 2264 possess the special meaning of “wild card”, which SHALL have a ‘match all’ effect for file queries. 2265 12.7.2.2.5 File Type 2266 This value SHALL indicate the specific file type. Manufacturer specific file type values SHALL be 2267 supported. The file types SHALL be defined per the table below: 2268 Table 12-10: File Type Values.

File Type Values Description 0x0000 – 0xffbe Manufacturer Specific 0xffbf Software Image 0xffc0 Security credential 0xffc1 Configuration 0xffc2 Log 0xffc3 – 0xfffe Reserved (unassigned) 0xffff Reserved: wild card

2269 File type value 0xFFFF SHALL have the special meaning of wild card, supporting a ‘match all’ effect for 2270 file queries. 2271 12.7.2.2.6 File Version 2272 For software image file types, file version should be defined as follows.

2273 Table 12-11: RECOMMENDED File Version Definition.

Smart Energy Profile 2.0 Page 80 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

# of Data Type Field Names Octets

2 Unsigned Image Release # 16-bit integer

2 Unsigned Image Build # 16-bit integer

2274 2275 A higher file version number indicates a newer file. For example: 2276 File version A: 0x00010005 represents image release 1 build 5. 2277 File version B: 0x0001000A represents image release 1 build 10. 2278 File version B is newer than File version A because its image version is higher. 2279 For non software image files, the file version may be defined differently to represent version schemes for 2280 different file types. For example, the version scheme for a security credential file may be different than 2281 that of a log file or configuration file. The implementation is manufacturer specific. 2282 12.7.2.2.7 Header String 2283 This is a manufacturer specific string that may be used to store other required information. The string 2284 SHALL occupy 32 octets. 2285 12.7.2.2.8 Total File Size 2286 Total file size SHALL be the sum of the header size and size of all sub-elements (in octets). It is the total 2287 number of octets transferred from FS to LD. 2288 12.7.2.3 Sub-element Format 2289 Sub-elements SHALL be composed of an identifier, followed by a length field, followed by data. The 2290 identifier provides for forward and backward compatibility as new sub-elements are introduced. Existing 2291 devices that do not understand newer sub-elements SHALL ignore the newer sub-elements. 2292 Table 12-12: Sub-element format.

Octets 2-octets 4-octets Variable

Data SID Length Field Data

2293 12.7.2.3.1 SID 2294 The sub-element identifier SHALL denote the type and format of the data contained within the sub- 2295 element. Identifiers in the range of 0x0000 to 0xefff SHALL be reserved for use within this specification. 2296 Identifiers in the range 0xf000 – 0xffff SHALL be reserved for manufacturer specific usage. The first 2297 four octets of the data Section of a manufacturer specific sub-element SHALL contain the manufacturer’s 2298 IANA assigned Private Enterprise Number. The remainder of the data Section SHALL be defined as the 2299 manufacturer sees fit.

Smart Energy Profile 2.0 Page 81 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2300 12.7.2.3.2 Length Field 2301 This value SHALL be the length (in octets) of the data Section of the sub-element. It does not include the 2302 SID or itself. 2303 12.7.2.3.3 Data 2304 The length of the data in the sub-element SHALL be equal to the value of the Length Field (in octets). 2305 The type and format of the data contained in the sub-element is specific to the SID. 2306 12.7.2.4 File Data Sub-element 2307 This sub-element contains file data to be loaded onto the device.

2308 Table 12-13: File Data.

Octets 2-octets 4-octets Variable

Data SID: 0x0000 Length of Data Data

2309 2310 The SID field SHALL be set to 0x0000 2311 The Length field SHALL be set to the length (in octets) of the variable length Data field (the actual file 2312 contents). 2313 The content of the Data field (the file content) is opaque to this specification. 2314 2315 12.7.2.5 ECDSA Signature Sub-element 2316 The ECDSA Signature sub-element contains a digital signature for the file. The signature authenticates 2317 the source of the file and insures that the file has not been altered since signed. If a file contains an 2318 ECDSA Signature Sub-element, it SHALL be the last sub-element in the file. The signature SHALL be 2319 calculated over the entire file, this sub-element excluded. 2320

2321 Table 12-14: ECDSA Signature.

Octets 2-octets 4-octets 4-octets 42-octets

Data SID: 0x0001 Length Signer IANA Signature Data PEN

2322 2323 The SID field SHALL be set to 0x0001 2324 The Length field SHALL be set to the sum of the lengths (in octets) of the Signer IANA PEN and 2325 Signature Data fields (46). 2326 The Signer IANA PEN field SHALL contain the signer’s IANA assigned Private Enterprise Number.

Smart Energy Profile 2.0 Page 82 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2327 The Signature Data field SHALL contain the ECDSA signature of the file contents. 2328 12.7.2.6 ECDSA Signer Certificate Sub-element 2329 This sub-element contains the signer’s ECDSA certificate.

2330 Table 12-15: ECDSA Signer Certificate Sub-element.

Octets 2-octets 4-octets 48-octets

Data SID: 0x0002 Length ECDSA Signer Certificate

2331 The SID field SHALL be set to 0x0002 2332 The Length field SHALL be set to the length (octets) of the ECDSA Certificate field (52). 2333 The ECDSA Certificate field SHALL contain the ECDSA Signer Certificate. 2334 2335 12.7.2.7 RSA Signature Sub-element 2336 The RSA Signature sub-element contains a digital signature for the file. The signature authenticates the 2337 source of the file and insures that the file has not been altered since signed. If a file contains an RSA 2338 Signature Sub-element, it SHALL be the last sub-element in the file. The signature SHALL be calculated 2339 over the entire file, this sub-element excluded. 2340 Table 12-16: RSA Signature.

Octets 2-octets 4-octets 4-octets TBD-octets

Data SID: 0x0003 Length Signer IANA Signature Data PEN

2341 2342 The SID field SHALL be set to 0x0003 2343 The Length field SHALL be set to the sum of the lengths (in octets) of the Signer IANA PEN and 2344 Signature Data fields. 2345 The Signer IANA PEN field SHALL contain the signer’s IANA assigned Private Enterprise Number. 2346 The Signature Data field SHALL contain the RSA signature of the file contents. 2347 12.7.2.8 RSA Signer Certificate Sub-element 2348 This sub-element contains the signer’s RSA certificate. 2349

2350 Table 12-17: RSA Signer Certificate Sub-element.

Octets 2-octets 4-octets TBD-octets

Smart Energy Profile 2.0 Page 83 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

Data SID: 0x0004 Length RSA Signer Certificate

2351 2352 The SID field SHALL be set to 0x0004. 2353 The Length field SHALL be set to the length (octets) of the RSA Signer Certificate field. 2354 The RSA Signer Certificate field SHALL contain the RSA Signer Certificate.

2355 12.7.3 File Names 2356 This specification makes no recommendations regarding file naming conventions.

2357 12.7.4 Signatures 2358 Smart Energy 2.0 SHALL require manufacturer specific files be signed by the manufacturer. 2359 Manufacturer specific files SHALL include software image and security credential file types. 2360 LDs SHALL only accept manufacturer specific files that contain one and only one signature sub-element. 2361 If a file requiring signing does not contain a signature sub-element, the LD SHALL discard the file and 2362 post LE_MISSING_SIGNATURE to the LogEvent log. 2363 If a file requiring signing contains more than one signature sub-element, the LD SHALL discard the file 2364 and post LE_BAD_SIGNATURE to the LogEvent log. 2365 The signature sub-element SHALL be the last sub-element in the file, otherwise the LD SHALL discard 2366 the file and post an LE_BAD_SIGNATURE to the LogEvent log. 2367 The LD MUST verify the signature as described in the following Sections prior to activating the 2368 downloaded file contents. 2369 Note that device unique files (log files, configuration files, etc.) are not considered manufacturer specific 2370 and SHALL not be REQUIRED to be signed.

2371 12.7.4.1 Signature Calculation 2372 File signature calculation SHALL be performed as follows: 2373 1. A valid file image SHALL have previously been created including all the necessary header fields, 2374 sub-elements, data fields, etc. This MAY or MAY NOT include a signer certificate sub-element. 2375 2. An ECDSA or RSA signature sub-element SHALL be constructed, including only its SID, the 2376 length field, and the manufacturer’s IANA PEN (the signature data has not yet been calculated). 2377 The signature sub-element SHALL be appended to the file. 2378 3. The file header SHALL be updated with a new total image size which includes the full size of the 2379 signature sub-element (including signature data which has not yet been appended). 2380 4. The appropriate message digest SHALL be calculated over the entire image (note signature data 2381 is not included). 2382 5. The public key corresponding to the manufacturer signer certificate SHALL be obtained.

Smart Energy Profile 2.0 Page 84 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2383 6. The ECDSA or RSA algorithm SHALL be used to calculate the file signature using the message 2384 digest and the manufacturer signer public key. 2385 7. The signature is placed in the signature field of the signature sub-element at the very end of the 2386 file.

2387 12.7.4.2 Signature Verification 2388 The signature of a completely downloaded file SHALL be verified as follows. 2389 1. The device SHALL first determine if the signer of the image is the device manufacturer. 2390 a. The device SHALL extract the signer IANA PEN from the signature sub-element. 2391 b. If a signature sub-element is not found, then the file SHALL be discarded as invalid and 2392 the device SHALL post LE_MISSING_SIGNATURE to the device LogEvent log. 2393 c. The device SHALL compare the extracted signer IANA PEN with its own manufacturer 2394 IANA PEN. If the two PENs do not match, the file SHALL be discarded as invalid and 2395 the device SHALL post LE_BAD_SIGNER to the device LogEvent log. 2396 2. If the file includes a signer certificate sub-element: 2397 a. The device SHALL extract the signer certificate data from the signer certificate sub- 2398 element. 2399 b. The device SHALL verify that the signer IANA PEN within the signature sub-element 2400 matches the subject field of the extracted signer certificate. 2401 c. If a match is not found, the file SHALL be discarded as invalid and the device SHALL 2402 post LE_BAD_SIGNER_CERTIFICATE to the device LogEvent log. 2403 d. The device SHALL verify that the extracted signer certificate chains correctly to the 2404 manufacturer root. If it does not, the files SHALL be discarded as invalid and the device 2405 SHALL post LE_BAD_SIGNER_CERTIFICATE to the LogEvent log. 2406 e. The extracted signer certificate becomes the activated signer certificate. 2407 3. The device SHALL calculate the message digest over the entire file except the signature field of 2408 the signature sub-element (the last field in the file). 2409 4. The signer’s public key SHALL be obtained by extracting it from the activated signer certificate. 2410 5. The device SHALL then pass the calculated digest value, signer certificate, and signer public key 2411 to the signature verification algorithm. 2412 6. If the signature algorithm returns success, then the file SHALL be considered valid. 2413 7. If the signature algorithm returns fail, the file SHALL be discarded as invalid and the device 2414 SHALL post LE_BAD_SIGNATURE to the device LogEvent log. 2415 An LD verifies file signatures using the public key from the manufacturer signer certificate. The signer 2416 certificate may be obtained in one of two ways: pre-installation of the signer certificate on the LD, or 2417 reception of the signer certificate within a downloaded file. 2418 An LD that does not have a signer certificate pre-installed SHALL only accept signed files that include a 2419 signer certificate sub-element. If such a device receives a file that contains a signature sub-element but 2420 does not contain a signer certificate sub-element, then the device SHALL discard the file and post 2421 LE_MISSING_SIGNER_CERTIFICATE to the LogEvent log

Smart Energy Profile 2.0 Page 85 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2422 The signer certificate SHALL chain correctly to the signer root certificate, which SHALL be preinstalled 2423 on the device. Upon power up or reception of a new signer certificate, the LD SHALL validate the signer 2424 certificate versus the signer root certificate. Successful validation of the signer certificate SHALL place 2425 the signer certificate into the activated state (ready to be used for signature verifications). Detection of an 2426 invalid signer certificate SHALL cause the LD to post an LE_INVALID_SIGNER_CERTIFICATE to the 2427 device’s LogEvent log. 2428 12.7.5 Files Function Set 2429 The Files function set is a set of resources exposed by the FS, enabling an LD to query for available files, 2430 load files, report load status of files, and activate files. 2431 12.7.5.1 Sequence Diagram 2432 The sequence diagram below describes how the Files function set resources interact to support secure LD 2433 download of files.

Smart Energy Profile 2.0 Page 86 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

LD FS

LD queries for the list of available GET /files/available files. LD downloads a file

GET the file LD reports Downloads the status of complete the file download PUT /files/status

GET /files/activation LD queries for the time at LD reports which the the status of loaded file the file should be activation activated.

LD activates file

PUT /files/status

2434 2435 Figure 12.7-1: Sequence Diagram - Files Function Set. 2436 12.7.6 Available Files Resource 2437 12.7.6.1 Overview 2438 The LD queries the Available Files resource on the FS to determine if there are any new files waiting to 2439 be downloaded to the LD. 2440 An FS SHALL implement this resource. 2441 12.7.6.2 Dependencies 2442 There are no dependencies on other function sets.

Smart Energy Profile 2.0 Page 87 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2443 12.7.6.3 Sequence Diagrams 2444 See above. 2445 12.7.6.4 URI Structure 2446 Table 12-18: URI Structure Table for the Available Files Resource. URI Allowed Methods /files/available Resource URI GET PUT POST DELETE X

2447 12.7.6.4.1 URI Actions 2448 12.7.6.4.2 GET 2449 GET /files/available SHALL return an XML representation of an AvailableFilesList resource, which 2450 SHALL be a valid instance per the XML schema described in TBD. 2451 The client (LD) would send: 2452 GET /files/available? 2453 type=0xFFBF& 2454 devid=01:23:45:67:89:ab& 2455 mfHwVer=abc123& 2456 mfId=37244& 2457 mfInfo=UpToTheManufacturer& 2458 mfModel=123abc& 2459 mfSerNum=123.456-789& 2460 swVer=01.23-45?76 HTTP/1.1 2461 Host: {Host} 2462 2463 …where the query parameters SHALL be defined as… 2464 Table 12-19: Query Parameters. Query Description Mandatory/OPTIONAL Parameter type Type of file queried. This parameter SHALL follow O identical syntax and semantics as the file types

defined in Table 3. Omission SHALL mean query for all file types. devid EUI64 of the device M mfHwVer Hardware version. This parameter SHALL follow M identical syntax and semantics as the element of the same name from the DeviceInformation resource. mfId Manufacturer ID. This parameter SHALL follow M identical syntax and semantics as the element of the same name from the DeviceInformation resource. mfInfo Manufacturer Information. This parameter SHALL M follow identical syntax and semantics as the element of the same name from the DeviceInformation

Smart Energy Profile 2.0 Page 88 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

resource. mfModel Model Number. This parameter SHALL follow M identical syntax and semantics as the element of the same name from the DeviceInformation resource. mfSerNum Serial number. This parameter SHALL follow M identical syntax and semantics as the element of the same name from the DeviceInformation resource. swVer Activated software version. This parameter SHALL M follow identical syntax and semantics as the element of the same name from the DeviceInformation resource. 2465 The server (FS) would respond: 2466 2467 HTTP/1.1 200 OK 2468 Content-Type: application/xml 2469 2470 2471 2472 2473 2474 0xFFBF 2475 128000 2476 2477 2478 The FS SHALL provide at most one File of a specific type in the response. 2479 12.7.6.5 Subscription / Notification Behavior 2480 Subscription / notification behavior is not supported. 2481 12.7.6.6 Application Guidelines / Behavior 2482 This resource is read-only. 2483 12.7.6.7 LogEvents Generated 2484 There are no LogEvents generated by this resource. 2485 12.7.7 File Status Resource 2486 12.7.7.1 Overview 2487 The LD updates file status to the File Status resource on the FS, informing the FS of the progress of any 2488 LD file loads. 2489 An FS SHALL implement this resource. 2490 12.7.7.2 Dependencies 2491 There are no dependencies on other function sets. 2492 12.7.7.3 Sequence Diagrams 2493 See above.

Smart Energy Profile 2.0 Page 89 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2494 12.7.7.4 URI Structure 2495 Table 12-20: URI Structure Table for the File Status Resource. URI Allowed Methods /files/status Resource URI GET PUT POST DELETE X

2496 12.7.7.4.1 URI Actions 2497 12.7.7.4.2 PUT 2498 The FileStatus resource sent to the FS SHALL be an XML representation valid per the XML schema 2499 described in TBD.

2500 The client (LD) would sends 2501 PUT /files/status HTTP/1.1 2502 Host: {host} 2503 2504 2505 2506 2507 01 2508 01:23:45:67:89:ab 2509 2510 The server (FS) would respond: 2511 HTTP/1.1 200 OK 2512 12.7.7.5 Subscription / Notification Behavior 2513 Subscription/ notification behavior is not supported. 2514 12.7.7.6 Application Guidelines / Behavior 2515 For non signed files, LDs SHALL PUT to the FS File Status resource immediately after reception and 2516 verification check of file correctness, informing of the success or failure of the file load. 2517 For signed files, LDs SHALL POST to the FS File Status resource immediately after reception and 2518 verification check of file signature, informing of the success or failure of the file load and signature 2519 verification. 2520 For all files, the LD SHALL POST to the FS File Status resource immediately after activation of the file. 2521 12.7.7.7 LogEvents Generated 2522 There are no LogEvents generated by this resource. 2523 12.7.8 File Activation Resource 2524 12.7.8.1 Overview 2525 The LD queries the File Activation resource to determine the time at which a loaded file should be 2526 activated. 2527 An FS SHALL implement this resource.

Smart Energy Profile 2.0 Page 90 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2528 12.7.8.2 Dependencies 2529 LD requires accurate time to support activation. 2530 12.7.8.3 Sequence Diagrams 2531 Not applicable. 2532 12.7.8.4 URI Structure 2533 Table 12-21: URI Structure Table. URI Allowed Methods /files/activation Resource URI GET PUT POST DELETE X

2534 12.7.8.4.1 URI Actions 2535 12.7.8.4.2 GET 2536 GET /files/activation SHALL return a XML representation of an Activation resource, which SHALL be 2537 valid per the XML schema described in TBD. 2538 The client (LD) would send: 2539 GET /files/activation? 2540 file=http://{FS Host}/file1.bin; 2541 devid=01:23:45:67:89:ab HTTP/1.1 2542 Host: {host} 2543 …where the query parameters are defined as… 2544 Table 12-22: Query Parameters. Query Description Mandatory/OPTIONAL Parameter file The URL identifying the file. M devid EUI64 of the device M 2545 The server (FS) would respond: 2546 HTTP/1.1 200 OK 2547 Content-Type: application/xml 2548 2549 2550 2551 214748364 2552 214749364 2553 2554 2555 12.7.8.5 Subscription / Notification Behavior 2556 Subscription/ notification behavior is not supported. 2557 12.7.8.6 Application Guidelines / Behavior 2558 This resource is read-only.

Smart Energy Profile 2.0 Page 91 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2559 12.7.8.7 LogEvents Generated 2560 There are no LogEvents generated by this resource. 2561

2562 2563 2564

Smart Energy Profile 2.0 Page 92 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2565 13 Smart Energy Resouces (formerly:Application Layer Business Objective Messages)

2566 13.1 Common Functionality (formerly: Common Application Functionality) 2567 13.1.1 Overview 2568 This Section describes common application functionality guidelines for features like randomization and 2569 active URIs that apply to more than one function set or in circumstances like adjacent or superseding 2570 events where special cases arise or need clear guidance to result in predictable behavior. 2571 This Section is organized in an overarching manner by logical topic, which is not indicative of 2572 prioritization or precedence. The topics discussed are: 2573 - Active URIs

2574 - Event Rules and Guidelines

2575 - Randomization

2576 - Multiple ESIs

2577 13.1.2 Active URIs 2578 The Active URI of a function set allows client devices to easily find the active instance of a specific 2579 resource. This makes it easier for constrained devices to find the information they are looking for without 2580 the need to explore a large list. Many of the function sets will provide this resource, including Demand 2581 Response, Messaging, and Pricing. 2582 It is important that the resource be managed carefully as the potential for race conditions arises when the 2583 same information exists in multiple locations. Therefore it is RECOMMENDED that the active URI of a 2584 resource be nothing more than a link to the actual instance of the resource that has become active. While 2585 this requires devices to perform an additional step, it will keep elements manageable and reduce the 2586 chances for race conditions. 2587 For example, the client can find the URI of active events when it retrieves the list of all events that are 2588 part of a given Demand Response Program. 2589 For example: 2590 The client would send: 2591 GET /dr/0/edc HTTP/1.1 2592 Host: {Host1}

2593 The server would respond: 2594 HTTP/1.1 200 OK 2595 Content-Type: application/xml 2596 2597 2598 2599 /dr/0/actedc 2600 2601 2631 2632 2633 … 2634 2635 2636 The device then has a link to the actual active instance(s). If there are multiple active instances, the URI 2637 request would return additional links. 2638 13.1.3 Event Rules and Guidelines 2639 These rules and guidelines are meant to specify client behavior in situations in which adjacent, nested, or 2640 overlapping events could cause clients to behave in an unexpected or undesirable manner. 2641 Except where otherwise noted, these apply to all function set clients. 2642 For the purposes of this Section, an event refers to any instance of a function set with a defined valid 2643 duration for which a client should take action. 2644 13.1.3.1 Definitions 2645 Start Time – Contained within the interval attribute of a event resource representation and indicates 2646 when the event should start. 2647 Duration – Contained within the interval attribute of a event resource representation and indicates for 2648 how long the event is valid. 2649 Specified End Time – Time when an event completes as specified in the instance’s interval attribute. 2650 This is calculated by adding Duration to Start Time. 2651 Scheduled Period - Represents the time between the Start Time and the Specified End Time of the event. 2652 Effective Start Time - Represents time at which an instance’s interval attribute indicates commencement 2653 based on the Start Time plus or minus any Start Randomization offsets.

Smart Energy Profile 2.0 Page 94 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2654 Effective End Time - Represents time at which an instance’s interval attribute indicates completion 2655 based on the Start Time plus Duration, plus or minus any End Randomization offsets. 2656 Effective Scheduled Period - Represents the time between the Effective Start Time and the Effective End 2657 Time. 2658 End Randomization – The maximum amount of time to be used when randomizing the completion of an 2659 event. 2660 Overlapping Event - Defined as an event where the Scheduled Period covers part or all of an existing, 2661 previously scheduled event. 2662 Start Randomization – The maximum amount of time to be used when randomizing the commencement 2663 of an event. 2664 Successive Events - Defined as two events where the Specified End Time of the first event is equal the 2665 Start Time of a subsequent scheduled event. 2666 Nested Events - Defined as two events where the scheduled Start Time and Specified End Time of the 2667 second event falls during the Scheduled Period of the first scheduled event and the second event is of 2668 shorter duration than the first event. 2669 13.1.3.2 Rules and Guidelines 2670 In the text below, some rules and guidelines will be identified as specific to “function sets with direct 2671 control.” These function sets exert direct control over clients’ behavior and are typically used to manage 2672 service provider infrastructure through incentive programs to the HAN owner. This is in contrast with 2673 informational function sets that provide data to clients for display and awareness purposes such as 2674 Billing, Messaging, and Pricing. Function sets with direct control primarily include DRLC and DER. 2675 Pricing is somewhat unique in that it exerts control-like effects upon price responsive clients; however, it 2676 is not a form of direct control from the service provider’s point of view. 2677 The depicted behaviors and required application management decisions are driven from the following 2678 guidance and rule set: 2679 1. Editing of a scheduled or active event is not allowed. Service providers SHALL cancel events 2680 they wish clients not act upon and provide new instances. This applies to all function set 2681 instances.

2682 2. For function sets with direct control and the Pricing function set, clients cannot be expected to 2683 support nested events and overlapping events. The rules below clarify the expected behavior in 2684 cases in which either of these situations arises.

2685 3. The current active event will be considered completed if a new event is started.

2686 4. When comparing two nested or overlapping events, the CreatedOn element is used to determine 2687 which event is newer and therefore supersedes the older. The event with the larger (e.g., more 2688 recent) CreatedOn date-time is the newer event. 2689 5. Upstream event systems and/or the ESI SHALL prevent mismanaged scheduling of Overlapping 2690 Events or Nested Events. Upstream event systems and/or the ESI will need to react to changing 2691 conditions by sending Overlapping Events or Nested Events to supersede previous directives, 2692 especially in the case of function sets with direct control. However, those systems MUST 2693 implement proper auditing and management rules to prevent a cascading set of error conditions 2694 propagated by improperly scheduled events.

Smart Energy Profile 2.0 Page 95 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2695 6. When needed, Upstream event systems and/or the function set server MAY resolve any event 2696 scheduling conflicts by performing one of the following processes:

2697 a. Canceling individual events starting with the earliest scheduled event and reissuing a new 2698 set of events.

2699 b. Canceling all scheduled events and re-issuing a new set of events.

2700 c. Or, in the case of function sets with direct control, sending Overlapping Events or Nested 2701 Events to supersede previous directives.

2702 7. For function sets with direct control, it is RECOMMENDED that process 6.c be used for most 2703 situations since it can allow a smoother change between two sets of directives but in no way does 2704 it negate the responsibilities identified in rule {#}5.

2705 8. Clients SHALL verify the Status of an event before acting upon it and every 5 minutes while 2706 acting upon it. If the Status timestamp has changed since last checked, and if the event Status is 2707 “Partially Superseded”, clients SHALL check all events from that function set instance that may 2708 supersede the original event. 2709 9. When a client receives an event with the Specified End Time in the past (Specified End Time < 2710 Current Time), this event is ignored.

2711 a. For function sets with direct control, clients will POST a Response to the ESI with a 2712 Status of “Rejected - Event was received after it had expired”.

2713 10. When a client receives an event with a Start Time in the past and a Specified End Time in the 2714 future ((Start Time + Start Randomization < Current Time) AND (Specified End Time > Current 2715 Time)), the client begins the event immediately and disregards any Start Randomization 2716 attributes. For response reporting purposes, the Effective Start Time is set to the current time. For 2717 event duration purposes, the Specified End Time is preserved, including any End Randomization 2718 attributes.

2719 a. If the client receives an event with a Start Time in the past but the latest possible Effective 2720 Start Time in the future and a Specified End Time in the future but where the full duration 2721 of the start randomized interval has not completed (Start Time + Start Randomization > 2722 Current Time) AND (Specified End Time > Current Time), then the client SHALL 2723 calculate an Effective Start Time based on the Start Time + Start Randomization. Note 2724 that this MAY result in the client calculating an Effective Start Time value in the past, in 2725 which case the client begins the event immediately. For response reporting purposes, the 2726 Effective Start Time is reported.

2727 b. If the client receives an event with Start Time in the future but the earliest possible 2728 Effectivce Start Time in the past, the client SHALL randomize over the remaining period 2729 between the Current Time and the Start Time.

2730 11. For function sets with direct control, regardless of the state of an event (scheduled or active), 2731 when a client detects an Overlapping Event condition, the latest Overlapping Event will take

Smart Energy Profile 2.0 Page 96 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2732 precedence over the previous event. Depending on the state of the event (scheduled or active), 2733 one of the following steps SHALL take place:

2734 a. If the previous event is scheduled and not active, the client will POST a Response 2735 (referencing the previous event) with the Status of “The event has been superseded.” 2736 After the Response has been successfully POSTed, the client can remove the previous 2737 event scheduled.

2738 b. If the previous event is active, the client SHALL change directly from its current state to 2739 the requested state at the effective start time of the Overlapping Event. The client will 2740 POST a Response (referencing the previous event) with the Status of “The event has been 2741 superseded.”

2742 12. Randomization SHALL NOT cause event conflicts or unmanaged gaps. To clarify:

2743 a. When randomization is used and the Effective End Time overlaps the Effective Start Time 2744 of a Successive Event, the Effective Start Time takes precedence. Events are not reported 2745 as superseded. Clients should report event statuses as it would a normal set of Successive 2746 Events.

2747 b. For consecutive events, clients SHALL coordinate the End Randomization value of an 2748 expiring event with the Start Randomization value of the successive event of the same 2749 function set to help prevent unexpected gaps between events. It is RECOMMENDED 2750 that a service provider coordinate randomization values where appropriate to facilitate 2751 orderly operation.

2752 c. Devices SHALL NOT artificially create a gap between Successive Events.

2753 13. It is permissible to have gaps when events are not Successive Events or Overlapping Events.

2754 14. If multiple EndDeviceCategoryTypes are identified for an event, future events for an individual 2755 EndDeviceCategoryType (or a subset of the original event) that cause an Overlapping Event will 2756 supersede the original event strictly for that EndDeviceCategoryType (or a subset of the original 2757 event). Note: Rule #6 applies to all Overlapping Events.

2758 a. Those clients whose EndDeviceCategoryType is not listed in the future event but whose 2759 EndDeviceCategoryType was included in the original event SHALL continue to execute 2760 per the parameters of the original event.

2761 b. Rule #1 continues to apply. Servers SHALL NOT edit the original event and maintain all 2762 events in whole.

2763 15. Servers SHALL maintain and serve events for the maximum Effective Scheduled Period. This 2764 applies even if the event in question is cancelled, so as to support devices that may have 2765 previously received a copy of the event from the server.

Smart Energy Profile 2.0 Page 97 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2766 16. Removal of an event from the server (e.g., due to limited storage space for the event list) SHALL 2767 NOT cause client to assume the event has been cancelled. Client devices SHALL only act on 2768 cancellation of events as indicated by an update to the event’s Status attribute, if applicable.

2769 13.1.4 Randomization 2770 13.1.4.1 Overview 2771 The primary goal of randomization is to mitigate the effect of simultaneous actions by large groups of 2772 devices on distribution infrastructure (e.g., in response to a control signal). Adverse effects include 2773 voltage surges or sags, which can ripple through the distribution infrastructure and cause serious 2774 reliability problems or damage to electronic devices. Randomization is also useful to the orderly 2775 shutdown of operations prior to an event taking place to ensure the desired response occurs at the desired 2776 time. Use of randomization is appropriate and necessary to ensure the reliable and orderly operation of 2777 commodity distribution infrastructure. 2778 The randomization mechanism is suitable for any function set that signals devices to change behavior or 2779 causes actions to be taken in response. It is intended as a common object for all function sets. The 2780 primary function sets that use randomization are DRLC and Pricing. The DER function set may also 2781 make use of randomization. 2782 13.1.4.2 Randomization Attributes 2783 Randomization is a subset of the randomizedDateTimeInterval attribute within an object or instance and 2784 consists of two signed attributes: randomizeEnd and randomizeStart. None, one, or both of these may be 2785 included as part of a function set instance. 2786 Randomization is implemented using signed integer(s) to indicate whether a HAN device executes a 2787 control action before or after the start or end (or both start and end) of the related event. Time granularity 2788 for randomization is one second. 2789 The randomization values (randomizeStart and randomizeEnd) are generated by the creator of the event. 2790 Clients acting on these events use these values as bounds for generating a local random offset to the start 2791 and end times, respectively, according to rules given below. Any client handling these events and not 2792 operating on them does not modify or apply them. 2793 13.1.4.2.1 randomizeStart 2794 The randomizeStart attribute represents the maximum number of seconds to be used when randomizing 2795 the commencement of an event and has a randomizeStart of 180 seconds, the device SHALL randomly 2796 select a number in seconds from zero to the randomizeStart specified for this event. Depending on the 2797 sign of the value (positive or negative), randomization SHALL be applied before or after the scheduled 2798 Start Time of the event. If the value is negative, randomization SHALL be applied before the specified 2799 Start Time of the event. 2800 For example, if an event is scheduled to start at 11:00AM and has a randomizeStart value of “-300” (e.g., 2801 five minutes prior randomization), a device could randomly generate a number of “-120” (e.g., two 2802 minutes prior randomization) and begin the event at 10:58AM. If the value is positive, randomization 2803 SHALL be applied after the specified Start Time of the event, causing the device to delay commencement 2804 of the event. The valid range for this attribute is -3600 to +3600 (e.g., +/-60 minutes). 2805 13.1.4.2.2 randomizeEnd 2806 The randomizeEnd represents the maximum number of seconds to be used when randomizing the end of 2807 an event. As an example, if randomizeEnd is set for 180 seconds, the device SHALL randomly select a 2808 number in seconds from zero to the randomizeEnd value specified for this event. Depending on the sign 2809 of the value (positive or negative), randomization SHALL be applied before or after the Specified End

Smart Energy Profile 2.0 Page 98 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2810 Time of the event. If the value is negative, randomization SHALL be applied before the Specified End 2811 Time of the event. 2812 For example, if an event is scheduled to conclude at 1:00PM and has a randomization randomizeEnd 2813 value of “-180”, a device can select to end the event at 12:59AM, indicating a negative 1 minute 2814 randomization. If the value is positive, randomization SHALL be applied after the Specified End Time of 2815 the event, causing the device to delay termination of the event. The valid range for this attribute is -3600 2816 to +3600 (e.g., +/-60 minutes). 2817 13.1.4.3 Application Guidelines / Behavior 2818 The values required to implement randomization represent relative time in seconds. Therefore, the signed 2819 values can be used to effect either positive or negative (relative to start/endtime) randomization. This 2820 method of operation subsumes 'fixed' randomization offsets depending on the actual values chosen by the 2821 device relative to the randomizeStart and randomizeEnd randomization bounds. 2822 Clients SHALL support randomization. Clients SHALL apply randomization attributes when present in 2823 an event’s RandomizedDateTimeInterval attribute. Absence of a randomizeStart or randomizeEnd value 2824 in an event indicates randomization is not to be applied to the commencement or completion of an event, 2825 respectively. 2826 Cancellation of an event SHALL cause clients to apply the randomizeEnd attribute to the completion of 2827 the event. 2828 If an event is in progress and user override occurs, the client SHALL respond to the control action 2829 without randomization. 2830 13.1.4.4 DRLC Function Set-specific Application Guidlelines 2831 There are no additional application guidelines for randomization in this context as compared to the 2832 guidelines already written. 2833 13.1.4.5 Pricing Function Set-specific Application Guidelines 2834 While strongly RECOMMENDED, Pricing clients are not required to follow the sign of randomization 2835 for Pricing function set messages. However, Pricing clients MUST observe the absolute value of the 2836 randomizeEnd or randomizeStart value for the randomization range when calculating the randomization 2837 value. 2838 13.1.5 Multiple ESIs 2839 13.1.5.1 Overview 2840 This Section gives a description of how server and client devices should interact at the application layer 2841 when there are multiple ESIs in the network, particularly in scenarios where there are multiple servers of 2842 a function set for the same commodity. There are several situations where this may occur; in some 2843 situations, one or more of the HAN’s ESIs may be coordinated beyond the HAN, but this is not required. 2844 These guidelines provide methods and guidelines to facilitate orderly and predictable operations. 2845 13.1.5.2 Registration 2846 One key element in a multiple ESI network is the registration of devices to ESIs. Devices need the 2847 capability of determining which ESIs in the network it should receive data from and act upon for a 2848 particular commodity per function set. Devices MUST complete the registration and service discovery 2849 process for each of the ESIs with which the user intends it to access information. 2850 There may also be ESIs the device discovers with which it is not registered, or the ESI does not allow 2851 devices to register. In this case, the ESI MAY provide “public” information (e.g., provided without 2852 explicit registration by the user) that devices MAY receive. Depending on the specific function set 2853 guidelines, this may also factor into the application guidelines for multiple ESI scenarios.

Smart Energy Profile 2.0 Page 99 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2854 13.1.5.3 Time 2855 Time coordination is an important aspect of multiple ESI scenarios. Each function set server that has a 2856 reference to time SHALL also serve its respective time to the HAN. Clients SHALL choose a primary 2857 time server in the HAN with which to align its internal time per the Time function set guidelines. The 2858 following are recommendations on how a client should choose its default time server: 2859 - If there are any time servers in the HAN that indicate a level 3 time quality (time obtained from 2860 external authoritative source such as NTP), a client should choose this server(s).

2861 - In a HAN with no time servers indicating a level 3 time quality, a device should choose the 2862 pricing server’s time.

2863 - In the event there are no time servers indicating a level 3 quality and there are no pricing servers, 2864 then a device should choose the Metering server’s time.

2865 - If none of the above criteria are met with time servers in the HAN, the device should choose the 2866 time server with a time quality indication nearest to level 3. If there are multiple servers with the 2867 same value, the device should choose the time server which best fits its application.

2868 As a best practice, it is RECOMMENDED that devices check the time servers available in the HAN once 2869 every 24 hours. 2870 For the purposes of arbitrating function sets on multiple ESIs, clients SHALL activate instances at the 2871 expected time on the server from which it received the function set instance. Clients following function 2872 sets on a server to which their internal Time source is not synchronized shall determine the delta when 2873 determining the moment at which to activate instances. 2874 In some scenarios where an ESI is serving function sets that exert control (e.g., DRLC or Pricing), the 2875 ESI’s time server MAY seek to align or offset its time signals in the HAN with those of the Metering 2876 server’s Time function set. This facilitates alignment of control and control-like signals with the 2877 Metering intervals captured by the premises’ metering aggregation point. 2878 13.1.5.4 Messaging Function Set 2879 Devices MAY obtain text messages from many ESIs, service providers, and/or other devices. It MAY be 2880 very common to have multiple messaging servers in a HAN. Server registration may also be used to 2881 allow a user to configure which messaging servers in the HAN the device should prioritize. Although 2882 server registration may be used, it is not required, and devices with enough resources MAY display 2883 messages from as many servers in the HAN as it wishes. In the event a device has limited resources 2884 available or a constrained user interface, devices SHOULD use the PriorityAttribute of the messaging 2885 message resource representation to prioritize which messages to present to the user. 2886 If a device uses server registration to determine which messaging servers to present to the user, the device 2887 SHALL periodically perform service discovery to determine if the registration has changed with new 2888 servers entering the HAN. 2889 13.1.5.5 Pricing Function Set 2890 For the purposes of price responsiveness, clients SHALL only follow one pricing server in the HAN per 2891 commodity. Clients MAY follow multiple Pricing servers for informational display purposes (e.g., to 2892 compare different providers) or price seeking behavior. More sophisticated devices (e.g., Premise Energy 2893 Management System) MAY follow multiple Pricing servers and make poliy based decisions to dispatch 2894 local resources (e.g., Distributed Energy Resource) and/or provide a single Pricing server for clients it 2895 controls based on user preferences.

Smart Energy Profile 2.0 Page 100 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2896 Registered devices SHALL discover their primary Pricing server and follow it for the purposes of price 2897 responsiveness. It is incumbent upon the user to choose the Pricing server with which to register the 2898 device. Devices SHALL periodically perform service discovery to find new pricing servers with which it 2899 is registered and begin following it for the purposes of price responsiveness. Clients SHALL follow the 2900 last Pricing server with which they were registered. Clients SHALL unsubscribe or discontinue following 2901 the previous Pricing server for the purposes of price responsiveness. In addition to periodic discovery of 2902 new Pricing servers, it is RECOMMENDED that devices allow a means of de-registration (or return to 2903 defaults) so the device can be manually de-registered and not require the periodic polling time. 2904 When devices are registered to a Pricing server, they SHALL ignore any “public” pricing servers that are 2905 present in the HAN or become available. 2906 13.1.5.6 Demand Response Load Control and Distributed Energy Resource Control Function 2907 There may be multiple coordinated or uncoordinated DRLC and DER Control in a HAN. With the ability 2908 to act on instances from multiple servers, which may not be coordinated in any way, there is the 2909 opportunity for conflicting/overlapping events that the client will need to handle. Clients SHALL only 2910 report acting on one event at a time and SHALL NOT respond to multiple DRLC and DER servers that 2911 they are acting on multiple events simultaneously. 2912 Clients SHALL determine the primacy of DRLC and DER Control based on the following: 2913 1. Instances from servers with which it is registered SHALL have precedence over instances from 2914 servers with which it is not registered (e.g., events from registered/enrolled servers trump events 2915 from “public” servers).

2916 2. Instances with a higher Primacy Type attribute SHALL have precedence over instances with a 2917 lower ProviderPrimacy attribute, as follows:

2918 o 0: Contracted premises service provider

2919 o 1: Convenience functionality service provider

2920 o 2: Other convenience functionality service provider

2921 o 3: Other

2922 3. Clients SHALL prioritize execution of DRLC and DER function set events with different 2923 Primacy Type attributes using the following guidelines:

2924 o 0 supersedes 1

2925 o 1 supersedes 2

2926 o 2 supersedes 3

2927 o If two instances are received with the same priority, then normal Event Rules and 2928 Guidelines apply (e.g., superseding based on scheduling)

2929 4. If a client is executing an event from one server and decides to execute an event from a different 2930 server per the application guidelines, the client SHALL send an opt-out Response .status to the 2931 server of the event that was superseded.

Smart Energy Profile 2.0 Page 101 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2932 This mechanism and these guidelines allow service providers to coordinate amongst themselves or for 2933 regulatory/legislative entities to enforce coordination. Reputable service providers should appropriately 2934 self-select their Primacy Types attribute so as not to disadvantage the consumer’s participation in their 2935 contracted DR or DER Control service providers programs. This method does not prevent unreputable 2936 providers from misrepresenting their communications. Consumers are responsible for selecting 2937 secondary service providers that do not violate the terms and conditions of their contracted service 2938 providers’ program and maximizes their economic benefit.

Smart Energy Profile 2.0 Page 102 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

2939 13.2 Demand Response and Load Control 2940 13.2.1 Overview 2941 This function set provides an interface for Demand Response and Load Control (DRLC). Client devices 2942 of this function set include thermostats and devices that support load control. Server devices of this 2943 function set include ESIs and premises energy management systems that may be acting as a proxy for 2944 upstream demand response / load control management systems and subsequent data stores. 2945 Servers expose load control events called “EndDeviceControls” (EDC) to client devices. All EDC 2946 instances will expose attributes that allow devices to respond to events that are explicitly targeted at their 2947 device type. For example, an EDC may contain an Offset object indicating a degree offset to be applied 2948 by a Smart Thermostat. The EDC will also expose necessary attributes that load control client devices 2949 will need in order to process an event. These include Start Time and Duration, as well as an indication on 2950 the need for randomization at the start and/or end of the event. 2951 13.2.2 Dependencies 2952 DRLC requires the following resources be present: 2953 - Servers: 2954 - Time

2955 - Response

2956 - Clients:

2957 - Time

2958 - Response

2959 13.2.3 URI Structure and Actions 2960 13.2.3.1 URI Structure 2961 Table 13-1: URI Structure Table for Demand Response and Load Control.

URI Model element Purpose

PUT

GET

POST DELETE /dr DemandResponse List of DemandResponseProgram instances. Program Devices implementing the /dr resource MAY M E O E support multiple instances of DemandResponsePrograms.

/dr/{#} Specific DemandResponseProgram collection M E O E resource. This resource can be thought of as a particular DemandResponseProgram endpoint.

103

November, 2011 Draft ZigBee-11167

2962

URI Purpose

PUT

GET

POST DELETE /dr/{#}/edc List of EndDeviceControls under one M E O E DemandResponseProgram. Devices

implementing the /dr/{#}/edc resource MAY support multiple EndDeviceControls.

/dr/{#}/edc/{#} Specific EndDeviceControl instance. This M O E O instance can be thought of as a particular

demand response / load control event for a period of time. /dr/{#}/aedc List of EndDeviceControls that are currently M E E E active.

2963 2964 13.2.4 Subscription / Notification Behavior 2965 When Demand Response and Load Control function set servers support subscriptions they SHALL 2966 provide the ability for clients to subscribe to a minimum of 4 of the following resources: 2967 - DemandResponseProgramList (e.g., /dr)

2968 The collection of DemandResponseProgram instances

2969 - EndDeviceControlList (e.g., /dr/{#}/edc)

2970 The collection of EndDeviceControls within one DemandResponseProgram

2971 - Active EndDeviceControlList (e.g., /dr/{#}/aedc)

2972 The collection of active EndDeviceControl instances

2973 - EndDeviceControl (e.g., /dr/{#}/edc/{#})

2974 A specific EndDeviceControl instance

2975 Client devices can subscribe to the DemandResponseProgram collection to be notified of any changes to 2976 the list. 2977 Client devices can subscribe to collections of EndDeviceControls under one or many 2978 DemandResponseProgram instances.

104

November, 2011 Draft ZigBee-11167

2979 Client devices can subscribe to a collection of active EndDeviceControl instances to receive updates when 2980 any change occurs to the list. 2981 Client devices can subscribe to a specific EndDeviceControl to stay up-to-date on any changes to the 2982 Status of a specific EDC, for instance, when a client wants to be notified if the event is cancelled. When 2983 the client device discovers a new instance of an EndDeviceControl, it can subscribe to that instance to 2984 allow it to be notified of any changes. 2985 13.2.4.1 Page List Ordering 2986 For paging purposes, the DemandResponseProgram list SHALL be ordered based on the 2987 following criteria: 2988 1. PrimacyType, where instances with a higher provider primacy are ordered first on the list. 2989 For paging purposes, the EndDeviceControl list and the active EndDeviceControl list SHALL be ordered 2990 based on the following criteria: 2991 1. DateTimeInterval.start, where instances with the earliest Effective Start Time are ordered before 2992 those with a lter Effective Start Time. 2993 2. creationTime, where instances with the latest creation time are ordered first on the list. 2994 3. mRID 2995 13.2.5 Application Guidelines / Behavior 2996 13.2.5.1 DemandResponseProgram 2997 Multiple programs can be created to target different types of devices or to offer different types of 2998 incentives. DemandResponseProgram SHALL use mRID as a unique identifier for each instance of a 2999 program, these SHALL NOT be reused until all possible values have been used. 3000 DemandResponseProgram server devices SHALL be capabale of internally sorting and supporting at 3001 least 1 DemandResponseProgram instance. DemandResponseProgram server devices SHOULD be 3002 capabale of internally sorting and supporting 3 unique DemandResponseProgram instances. 3003 13.2.5.2 EndDeviceControl 3004 An EndDeviceControl is used to provide control parameters to a DRLC client. EndDeviceControl 3005 SHALL use mRID as a unique identifier for every instance, these SHALL NOT be reused until all 3006 possible values have been used. An EndDeviceControl can always be overridden by the user. 3007 Demand Response/Load Control server devices SHALL be capable of internally storing and supporting at 3008 least 5 unique EndDeviceControl instances that MAY be distributed between multiple programs. Demand 3009 Response/Load Control server devices SHOULD be cabapable of internaly storing and supporting a total 3010 of 10 unique EndDeviceControl instances. Servers are responsible for maintaining EndDeviceControls on 3011 their list, including cancelled events, for the duration of the event plus the maximum start and end 3012 randomization allowable. Servers are also responsible for removing events from their list that have 3013 expired or have been cancelled and their effective end time has passed. If a server receives a new 3014 EndDeviceControl and no longer has room in its collection, it MAY remove an existing event to make 3015 room for the new one; however, this will not indicate that the event has been canceled. When clients do 3016 not see an event on the server’s list that they previously retrieved, they should make no assumption about 3017 the event being cancelled, deleted, or otherwise. Indeed, it may still be pending. Servers are responsible 3018 for selecting which events to remove to make room for new ones. 105

November, 2011 Draft ZigBee-11167

3019 Demand Response/Load Control client devices SHALL be capable of internally storing and supporting at 3020 least 3 unique EndDeviceControl instances. Demand Response/Load Control client devices SHOULD be 3021 capable of internally storing and supporting 5 unique EndDeviceControl instances. As a highly 3022 RECOMMENDED recovery mechanism, when a maximum of storage of events has been reached and 3023 additional EndDeviceControl instances are available on the server(s), clients SHOULD prioritize local 3024 storage and give preference to EndDeviceControls with start times in the near future and to events that 3025 have been flagged as mandatory. 3026 Devices that do not subscribe to the EndDeviceControl resource SHALL continue to poll every 5 minutes 3027 even when their event buffer is full. This will allow them to stay up to date on new events that MAY 3028 replace or supersede events already on their list. This will also keep devices aware of any events that are 3029 cancelled. 3030 13.2.5.3 Rules and Guidelines

3031 If an EndDeviceControl includes more than one control parameter, the DRLC client SHALL process the 3032 event and select the applicable parameter. If the DRLC client is capable of supporting multiple 3033 parameters from the ones that have been included in the event, it should select the parameter that best fits 3034 its functionality. 3035 13.2.5.3.1 EndDeviceCategoryType 3036 EndDeviceCategoryType is used within an EndDeviceControl to target a specific type of device. An 3037 EndDeviceControl MAY target multiple EndDeviceCategoryTypes. 3038 13.2.5.3.2 drProgramMandatory 3039 Events flagged as drProgramMandatory are strongly RECOMMENDED to be complied with. 3040 When a user attempts to opt-out of an EndDeviceControl with the drProgramMandatory flag set, clients 3041 SHALL require an extra acknowledgment from the user confirming the desire to opt-out. Clients 3042 SHOULD present a warning to indicate that this event has been flagged as mandatory by their service 3043 provider. For example, the client can present a screen stating that “Utility X has marked this event as 3044 mandatory and an opt-out can lead to financial penalties as agreed upon in the contract with Utility X.” 3045 3046 13.2.5.3.3 overrideDuration 3047 The overrideDuration attribute provides a duration, in seconds, for which a client device is allowed to 3048 override an EndDeviceControl as contractually agreed upon with a service provider. After the 3049 ovverideDuration time of an EndDeviceControl has elapsed, the client device SHALL return to execution 3050 of the EndDeviceControl for the remaining Effective Scheduled Period. 3051 Client devices SHALL NOT prevent users from opting out of EndDeviceControls containing an 3052 overrideDuration, but if the drProgramMandatory flag is set for the given event, they SHOULD provide 3053 a warning for non-compliance.

3054 13.2.5.3.3.1 DateTimeInterval 3055 DateTimeInterval provides two attributes, duration and start. 3056 The duration of the EndDeviceControl is provided in seconds using the duration attribute. Events 3057 SHALL not be longer than 86,400 seconds (1 day).

106

November, 2011 Draft ZigBee-11167

3058 13.2.5.3.4 responseRequired 3059 Client devices encountering EndDeviceControls with a responseRequired value of true SHALL provide 3060 the Demand Response server with the appropriate type of response, to the Response resource indicated in 3061 the replyTo field. 3062 13.2.5.4 Duty Cycle 3063 Duty cycle control is a device specific issue and SHALL be managed by the device. The duty cycle of 3064 the device under control should span the shortest practical time period in accordance with the nature of 3065 the device under control and the intent of the request for demand reduction. The default factory setting 3066 SHOULD be three minutes for each 10% of duty cycle1. This indicates that the default time period over 3067 which a duty cycle is applied is 30 minutes, meaning a 10% duty cycle would cause a device to be off for 3068 3 minutes. The “off state” SHALL precede the “on state”. 3069 13.2.5.5 Offset 3070 The Offset object is used to apply a change in temperature or load consumption to a specific device. The 3071 type attribute will indicate what type of offset that SHALL be applied. 3072 If a temperature offset is sent that causes the heating or cooling temperature set point to exceed the limit 3073 boundaries that are programmed into the device, the device SHALL respond by setting the temperature at 3074 the limit. 3075 If an EDC is being targeted at multiple devices or to a device that controls multiple devices (e.g., EMS), it 3076 can provide multiple Offset instances within one EDC. For events with multiple Offset instances, a client 3077 SHALL select the Offset that best fits their operating function. 3078 Alternatively, an event with a single Offset can be targeted at an EMS in order to request a percentage 3079 load reduction on the average energy usage of the entire premise. An EMS SHOULD use the Metering 3080 function set to determine the initial load in the premise, reduce energy consumption by controlling 3081 devices at its disposal, and at the conclusion of the event, once again use the Metering function set to 3082 determine if the desired load reduction was achieved. 3083 13.2.5.6 SetPoint 3084 If a temperature is sent that exceeds the temperature limit boundaries that are programmed into the 3085 device, the device SHALL respond by setting the temperature at the limit. 3086 When both a Temperature Offset and a Temperature Set Point are provided, the device MAY use either 3087 as defined by the device manufacturer. 3088 13.2.5.7 Status 3089 The Status object is used to indicate the current status of an EndDeviceControl. Devices can read this 3090 object to get the most up to date status of the event. Devices can also subscribe to a specific 3091 EndDeviceControl instance to get updates when any if its attributes change, including the Status object. 3092 Devices that do not subscribe to an EndDeviceControl instance SHALL read the instance before 3093 executing any event that has been scheduled in the past. These devices are also RECOMMENDED to 3094 read this resource every 5 minutes while the event is active. This will allow them to be aware of any 3095 changes during the event.

107

November, 2011 Draft ZigBee-11167

3096 The Status object provides the pontentiallySuperseded flag and pontentiallySupersededTime time stamp 3097 to make clients aware that the server is hosting other EndDeviceControls that MAY superseded the event 3098 the client is executing or planning to execute. When the pontentiallySuperseded flag is set to true, clients 3099 SHALL explore the EndDeviceControlList where they MAY find an event that supersedes the current 3100 event. If the client does not find a superseding event, it SHALL continue with the execution or planned 3101 execution of the current event, with the understanding that the potential of a superseding event did not 3102 apply to its corresponding device type. 3103 When an event status changes, the server SHALL update the Status object within the EndDeviceControl 3104 to indicate the new status, along with the time the new status became effective. The server SHALL notify 3105 all subscribers of a change to an EndDeviceControl instance. The server may also provide the reason for 3106 the change using the Reason attribute in the Status object, where it can provide a textual explanation of 3107 the change. 3108 There are five specified types of status. They are described below.

3109 - Scheduled

3110 This status indicates that the event has been scheduled and the event has not yet started. The 3111 server SHALL set the event to this status when the event is first scheduled and persist until the 3112 event has become active or has been cancelled. For EndDeviceControls with a start time less 3113 than or equal to the current time, this status SHALL never be indicated, the event SHALL start 3114 with a status of “Active”. 3115 Client devices SHALL be aware of Scheduled events in the server’s list, determine if the event 3116 applies to them, and store them in their event queque if their buffer allows. 3117 - Active

3118 This status indicates that the event is currently active. The server SHALL set the event to this 3119 status when the event reaches its earliest possible Effective Start Time and remain through the 3120 maximum Effective Sheduled Period or until the event is cancelled. 3121 Client devices SHALL be aware of Active events in the server’s list, determine if the event 3122 applies to them, and calculate the event’s Effective Start Time given the provided randomization 3123 parameters. Client devices SHALL NOT immediately activate events marked as Active by the 3124 server as randomization MAY cause unique Effective Start Times for each client. 3125 - Cancelled

3126 When EndDeviceControls are cancelled, the dateTime attribute SHALL be used to indicate the 3127 effective time of the cancellation. If a server would like to cancel the event immediately, it would 3128 provide a dateTime value with the current time. The server is responsible for maintaining the 3129 cancelled event in its collection for the duration of the original event, or until the server has run 3130 out of space and needs to store a new event. 3131 Client devices SHALL be aware of Cancelled events, determine if the Cancelled event applies to 3132 them, and cancel the event at the time indicated by the dateTime attribute. Client devices SHALL 3133 NOT apply randomization to the termination of the event. 3134 - Cancelled with Randomization 108

November, 2011 Draft ZigBee-11167

3135 EndDeviceControls that are cancelled with randomization will use the dateTime attribute to 3136 indicate the effective time. The server is responsible for maintaining the cancelled event in its 3137 collection for the duration of the Effective Scheduled Period. 3138 Client devices SHALL be aware of Cancelled with Randomization events, determine if the 3139 Cancelled event applies to them, and cancel the event at the time indicated by the dateTime 3140 attribute using the original settings for randomizaiton.

3141 - Superseded 3142 EndDeviceControls marked as Superseded are events that have been replaced by new events that 3143 target the same group of device types and overlap for a given period of time. Servers SHALL 3144 mark an event as Superseded at the earliest Effective Start Time of the overlapping event. Servers 3145 are responsible for maintaining the Superseded event in their collection for the duration of the 3146 Effective Scheduled Period. 3147 Client device encountering Superseded events SHALL terminate execution of the event 3148 immediately and commence execution of the new event. 3149 Editing of existing events is NOT allowed. Cancelling scheduled or active events IS allowed. A server 3150 MAY contain nested and/or overlapping events. Servers and clients SHALL detect and handle nested and 3151 overlapping events as per Section 11.1.3.2. 3152 Client SHALL terminate the current active event if a new event scheduled in the same time period and 3153 targeted for their device category is started. 3154 13.2.5.8 TargetReduction 3155 The TargetReduction object is used by a Demand Response service provider to provide a 3156 RECOMMENDED threshold that a device/premises should maintain its consumption below. For 3157 example, a service provider can provide a RECOMMENDED threshold of some kWh for a 3-hour event. 3158 This means that the device/premises would maintain its consumption below the specified limit for the 3159 specified period. The service provider SHALL use the Type attribute to indicate the type of unit being 3160 used to indicate the threshold and the Value attribute to indicate the desired threshold. 3161 13.2.5.9 Response 3162 If the responseRequired field indicates, clients of this function set SHALL use the Response resource, 3163 specified in the replyTo field of the EndDeviceControl, to report on their participation in an 3164 EndDeviceControl. Clients will POST a Response on the response server with a Status from Table 11-4 3165 for each action taken on the event. For example, a common sequence would have the device POSTing a 3166 Response of “Event Received” when it first receives the event, “Event Started” when it starts the event 3167 and “Event Completed” when it has completed the event. 3168 When overriding an event, client devices SHOULD provide a duration for the override using the 3169 drOverrideDuration attribute found in the Response object. This is useful for service providers and EMS 3170 in understanding for how long the client device will override the event and when it can expect the client 3171 device to return to shedding load. 3172 Table 13-2: Event Status Table. 0x00 Reserved

109

November, 2011 Draft ZigBee-11167

0x01 Event Received 0x02 Event Started 0x03 Event Completed 0x04 User has chosen to “Opt-Out”, user will not participate in this event 0x05 User has chosen to “Opt-In”, user will participate in this event 0x06 The event has been cancelled 0x07 The event has been superseded 0x08 Event partially completed with User “Opt-Out”. 0x09 Event partially completed due to User “Opt-In” 0x0A Event completed, no User participation (Previous “Opt-Out”) 0x0B Reserved 0x0C to 0xF7 Reserved 0xF8 Rejected - Invalid Cancel Command (Default) 0xF9 Rejected - Invalid Cancel Command (Invalid Effective Time) 0xFA Reserved 0xFB Rejected - Event was received after it had expired (Current Time > Start Time +Duration) 0xFC Reserved 0xFD Rejected - Invalid Cancel Command (Undefined Event) 0xFE Load Control Event command Rejected 0xFF Reserved

3173 3174 Additional guidelines on how the Response resource operates are provided in the Response Function Set. 3175 13.2.5.10 LogEvents Generated 3176 There are no LogEvents generated by this resource. 3177 13.2.5.11 Use of Parent Fields 3178 Demand Response Program 3179 Resource

110

November, 2011 Draft ZigBee-11167

3180 replyTo – SHALL NOT be used in this object. 3181 ResponseRequired – SHALL NOT be used in this object. 3182 signatureRequired – SHALL NOT be used in this object. 3183 Subscribable –This field SHALL be true if a given instance can be subscribed to. 3184 Identified Object 3185 Description – MAY contain a text description of this program. 3186 mRID – SHALL be set to a valid mRID. 3187 End Device Control 3188 Resource 3189 replyTo – SHALL be set to the URI of the intended response server if the 3190 ResponseRequired field is set to true. 3191 ResponseRequired – SHALL be set with appropriate value if a response is required to 3192 this event. 3193 signatureRequired – SHALL be set to true if the response is to be signed. 3194 Subscribable –This field SHALL be set to true if a given instance can be subscribed to. 3195 Identified Object 3196 Description – MAY contain a text description of this event. 3197 mRID – SHALL be set to a valid mRID. 3198

3199 13.3 Metering Function Set 3200 13.3.1 Overview 3201 Metering function set provides interfaces to exchange commodity mearurement information such as 3202 reading type and meter reading between HAN devices. The major resources are listed below:

3203  Usage Point (upt) – Logical meter point

3204  Reading Type (rt)

3205  Meter Reading (mr) – Meter reading associated to a Reading Type (rt)

3206  Reading (r) & Interval Reading (ir) 3207 13.3.2 Dependencies 3208 Metering requires the following server resources be present in the HAN: 3209 - Base function set (e.g., time, …)

3210 13.3.3 Sequence Diagrams 3211 Two major metering use cases are illustrated in the sequence diagram below. 111

November, 2011 Draft ZigBee-11167

3212 13.3.3.1 GET Meter Reading 3213 Use case that a metering client (e.g., In-Premises Display) queries meter reading from a usage point. This 3214 process includes several steps. Usage point resources (upt) are discovered in a service discovery process. 3215 Note that mirrored meter readings are provided by a metering host which could be an ESI or other HAN 3216 devices.

sd GET Meter Reading

PAN Device Usage Point

A PAN device does service discovery on the network to get devices that have usage point resource ()

Select a target usage point for meter reading()

GET Meter Reading Resources List()

HTTP response with list of reading types()

GET Meter Reading Type()

HTTP response with reading types()

GET Meter Readings()

HTTP response with meter readings()

3217 3218 Figure 13.3-1: Use Case – GET Meter Reading. 3219 3220 Steps: 3221 1) A HAN device does service discovery (mDNS/DNS-SD) on the network to find devices that have 3222 usage point resource. A GET of this resource returns a list of supported usage point resources 3223 with their associated URIs.

3224 2) HAN device requests a target usage point for meter reading resources it supports including a link 3225 to reading type resource.

3226 3) HAN device requests reading type based on the resource URIs obtained in Step 2). 112

November, 2011 Draft ZigBee-11167

3227 4) HAN device requests readings based on the resource URIs obtained in Step 2).

3228 Note that this multiple step process does not necessarily occur every time a HAN device requests a meter 3229 reading. If the HAN device learned the URI of a reading type in a meter on a previous read, the only step 3230 involved is Step 4). 3231 13.3.4 URI Structure and Actions 3232 All valid URI structures are listed in the following table for the metering function set. Allowable 3233 operations (e.g., GET, PUT, POST, and DELETE) for clients for each URI are also listed. Sample XML 3234 payloads can be found in the subsequent Sections. 3235 3236 13.3.4.1 URI Structures for Metering 3237 Table 13-3: URI Structure Table for Metering. URI - Purpose GET PUT POST DELETE http{s}://{Host1} /upt Usage point () resource list. Devices M N/A O O implementing the /upt resource MAY (HAN (sub meter (sub support multiple instances of meter device to post its meter to asset. not instance remove allowed record) its to instance

refresh record) the list)

/upt/{#} Usage point instance including M O O O resources it supports.

Sub meters such as gas and water meters MAY mirror their data to a mirroring host. A mirrored meter can delete its mirrored instance on mirroring host.

/upt/{#}/mr Meter Reading list including explicit M O O O URIs for each valid meter reading (for (for resources. posting mirrored mirrored meter meter instance readings) only) /rt Meter Reading type list M O O O

113

November, 2011 Draft ZigBee-11167

/rt/{#} Meter Reading type instance (fully M O O O expanded)

/upt/{#}/mr/{#}/r Reading or interval reading list of a M O O O particular meter reading. & /upt/{#}/mr/{#}/ir

/upt/{#}/mr/{#}/r/ Reading or interval reading instance of M O O O {#} a particular meter reading. & /upt/{#}/mr/{#}/ir/ {#}

3238 M – Mandatory 3239 O – OPTIONAL 3240 N/A – Not applicable 3241 Each meter server has a /upt resource containing resources for local meters and sub meters that are 3242 mirrored to it. Here is one possible scenario that two electric meters exist in a HAN. Both have a /upt 3243 resource. Electric Meter #1 (ESI integrated) has a /upt list which contains /upt/0 (meter itself) and /upt/1 3244 (mirrored gas meter). Electric Meter #2 also has ESI integrated and has a /upt list which contains only one 3245 instance /upt/0 (meter itself) but no other meter mirrored to it. Since both /upt are visible, a HAN device 3246 that does service discovery will find there are two /upt servers and it then has to decide which /upt server 3247 to query based on server’s record information. Note that although there are two /upt/0 instances in this 3248 case, they are two different servers with different hostnames and/or IP addresses. 3249 3250 13.3.4.2 URI Actions 3251 HTTP requests and responses exchanged between client and server are listed in the following Sections. 3252 3253 13.3.4.2.1 Usage Point (Meter) List 3254 Uses:

3255  To provide a list of metering function set instances such as electric meter, gas meter, water meter, 3256 and etc. with URIs. 3257 The Usage Point (Meter) List resource URI is:

3258 http{s}://{Host1}/upt

3259 13.3.4.2.1.1

114

November, 2011 Draft ZigBee-11167

3260 13.3.4.2.1.2 GET 3261 GET /upt returns a list (described by the schema) of Meters (UsagePoint), each with their own URI 3262 that is subordinate to this URI. Note that the XML data below is example only.

3263 The client would send: 3264 GET /upt HTTP/1.1 3265 Host: {Host1} 3266 3267 The server would respond: 3268 HTTP/1.1 200 OK 3269 Content-Type: application/xml 3270 Content-Length: xxx 3271 3272 3273 3274 3275 0001 3276 3277 0002 3278 3279 0 3280 3281 1 3282 3283 3284 0002 3285 3286 0001 3287 3288 0 3289 3290 1 3291 3292 3293 0004 3294 3295 0001 3296 3297 1 3298 3299 1 3300 3301 3302 0008 3303 3304 0001 3305 3306 2 3307 3308 1 3309 3310 3311 3312 Note that the "roleFlags" field is a data type of 16 bit hex bit mask enumeration with the following 3313 defined: 3314 Bit 1 = isMirror 3315 Bit 2 = isPremisesAggregationPoint

115

November, 2011 Draft ZigBee-11167

3316 Bit 3 = isPEV 3317 Bit 4 = isDER 3318 Bit 5-16 - Reserved 3319 3320 Valid service category kinds are listed below: 3321 0 – electricity 3322 1 – gas 3323 2 – water 3324 4 – pressure 3325 5 – heat 3326 6 – cooling 3327 7 – communication 3328 8 – time 3329 3330 Valid status values are 3331 0 = off 3332 1 = on 3333

3334 13.3.4.2.1.3 PUT 3335 Note that a PUT is not allowed since it would result in a replacement of entire meter list. 3336 3337 13.3.4.2.2 Usage Point (Meter) Instance 3338 Uses:

3339  To provide resources that a single meter supports such as meter reading types. Information on 3340 meter status is also provided here.

3341 13.3.4.2.2.1 3342 The Meter Instance resource URI is:

3343 http{s}://{Host1}/upt/{#}

3344 13.3.4.2.2.2 GET 3345 GET /upt/{#} returns a list of resources, each with their own URI that is subordinate to this URI. Note 3346 that the XML data below is example only. 3347 The client would send: 3348 GET /upt/0 HTTP/1.1 3349 Host: {Host1} 3350 3351 The server would respond: 3352 HTTP/1.1 200 OK 3353 Content-Type: application/xml 3354 Content-Length: xxx 3355 3356 3357 116

November, 2011 Draft ZigBee-11167

3358 0001 3359 3360 0002 3361 3362 0 3363 3364 1 3365 3366 3367 13.3.4.2.3 Meter Reading Type Instance 3368 Uses:

3369  To provide detail information on a meter reading type 3370 The Meter Reading Type resource URI is:

3371 http{s}://{Host1}/rt/{#}

3372 13.3.4.2.3.1 GET 3373 GET /rt/{#} returns a (described by the schema) meter reading type.

3374 The client would send: 3375 GET /rt/0 HTTP/1.1 3376 Host: {Host1} 3377 The server would respond: 3378 HTTP/1.1 200 OK 3379 Content-Type: application/xml 3380 Content-Length: xxx 3381 3382 3383 3384 3385 1 3386 1 3387 1 3388 12 3389 128 3390 3 3391 15 3392 72 3393 3394 3395 Note that the detailed definition on reading type and values in the XML can be found in the 3396 Application Guidelines Section. Also paging function SHALL be supported for this resource. 3397 PUT, POST, and DELETE may be used for a sub meter to refresh, append, or delete its meter 3398 reading type. 3399 13.3.4.2.4 Meter Reading Resource List 3400 Uses:

3401  To provide a list of meter reading resources that a meter supports 3402 The Meter Reading List resource URI is:

3403 http{s}://{Host1}/upt/{#}/mr 117

November, 2011 Draft ZigBee-11167

3404 13.3.4.2.4.1 GET 3405 GET /upt/{#}/mr returns a Meter Reading list (described by the schema) of meter readings 3406 (/upt/{#}/mr/{#}), each with their own URI that is subordinate to this URI. 3407 The client would send: 3408 GET /upt/0/mr HTTP/1.1 3409 Host: {Host1} 3410 3411 The server would respond: 3412 HTTP/1.1 200 OK 3413 Content-Type: application/xml 3414 Content-Length: xxx 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 13.3.4.2.5 Reading and Interval Reading 3430 Uses:

3431  To provide meter readings based on a meter reading type 3432 The URI for a Reading list based on a reading type is: 3433 http{s}://{host}/upt/{#}/mr/{#}/r

3434 13.3.4.2.5.1 3435 The URI for a Reading instance based on a reading type is: 3436 http{s}://{host}/upt/{#}/mr/{#}/r/{#}

3437 13.3.4.2.5.2

3438 13.3.4.2.5.3 GET 3439 Register read (/r)

3440 GET /upt/{#}/mr/{#}/r returns a representation (described by the schema) of register meter reading

3441 addressed by this URI. CurrentSummationDelivered is an example of this resource.

3442 The client would send: 3443 GET /upt/0/mr/0/r HTTP/1.1 3444 Host: {Host1} 3445

118

November, 2011 Draft ZigBee-11167

3446 The server would respond: 3447 HTTP/1.1 200 OK 3448 Content-Type: application/xml 3449 Content-Length: xxx 3450 3451 3452 3453 3454 315360000 3455 12 3456 3457 3458 Interval reads (/ir)

3459 GET /upt/{#}/mr/{#}/ir returns a representation (described by the schema) of interval meter readings 3460 list addressed by this URI. 3461 The client would send: 3462 GET /upt/0/mr/0/ir HTTP/1.1 3463 Host: {Host1} 3464 3465 The server would respond: 3466 HTTP/1.1 200 OK 3467 Content-Type: application/xml 3468 Content-Length: xxx 3469 3470 3471 3472 3473 3474 600 3475 315360000 3476 3477 12 3478 3479 3480 3481 600 3482 315360601 3483 3484 13 3485 3486 3487 3488 600 3489 315361201 3490 3491 9 3492 3493 3494 3495 3496 13.3.4.2.6 Mirroring Meter Reading 3497 The following section defines the establishment and maintenance of a metering mirror. Efforts have been 3498 made to streamline this process to minimize required interactions in order to reduce power requirements. 3499 Once a node has joined the network it may perform the following steps to create and maintain a mirror on 3500 another device: 119

November, 2011 Draft ZigBee-11167

3501 1. Use mDNS/DNS-SD to identify a host that serves Metering function set and supports mirroring. 3502 The mirroring host SHALL NOT advertise support for mirroring unless it has the resources 3503 available to host at least one additional mirror. 3504 2. Once the mirroring host is identified, the requesting device (client) then uses the response to 3505 identify a host. It then does a GET of device capabilities from the mirroring host to determine the 3506 URI of the Mirroring function set. 3507 3. Once the URI of the Mirroring function set has been identified, the Metering client SHALL 3508 POST to its host’s Mirroring Usage Point (e.g., /mup) data for the mirrored usage point (see URI 3509 structure table for more details). This POST SHALL contain at least the information through the 3510 definition of MirrorMeterReadings and ReadingType. The POST MAY also contain 3511 IntervalBlocks and Readings. The device requesting the mirror SHALL supply locally unique 3512 IDs for each of the MirrorMeterReadings. When the mirroring host receives this POST it SHALL 3513 copy the received data into the normal metering structure under the host Metering server’s 3514 UsagePoint structure, and it SHALL allocate enough resources to manage the mirror and its data. 3515 Once the data is on the mirroring host, that server establishes the security parameters, based on 3516 the host’s security policy. 3517 4. To post new data to the mirror, the Metering client SHALL POST MirrorMeterReadings 3518 containing Readings and/or IntervalBlocks to the resource identified in the host’s response to the 3519 POST that created the resource (e.g. /mup/3). The mirror host SHOULD only accept POSTs from 3520 the device that created the mirror. The ID attribute of the MirrorMeterReading is used by the host 3521 to associate the data in this POST with the MeterReading in the associated UsagePoint. The new 3522 data SHALL be added to the related UsagePoint resource structure. The mirroring server MAY 3523 decide when to remove data from the related UsagePoint resource structure. If new data arrives 3524 and there are not enough resources to store it, the mirroring host SHALL delete data to make 3525 room for the new. 3526 Servers MAY implement a timeout mechanism on a mirror. If a server does not hear from a mirror client 3527 for more than a specified time the server MAY remove the mirror resource and its related UsagePoint 3528 resource. The recommended timeout is 72 hours.

120

November, 2011 Draft ZigBee-11167

class MeterMirror

MirrorUsagePointList

0..* MirrorMeterReading

MirrorUsagePoint + description: String32 [0..1] + ID: int - Creation Time: dateTime + lastUpdateTime: dateTime [0..1] + manufacturerID: HexBinary32 0..* + NextUpdateTime: dateTime [0..1] + roleFlags: HexBinary16 + serialNumber: String20 + status: UInt8 1 1 Objects::Serv iceCategory PAP10 roleFlags IdentifiedObject Specifies the roles that this usage point + kind: ServiceKind ReadingType has been assigned. Bit 1 - isMirror + accumulationBehaviour: AccumulationBehaviourType [0..1] UInt8 Bit 2 - isPremisesAggregationPoint + commodity: CommodityType [0..1] Bit 3 - isPEV Types::Serv iceKind + consumptionTier: ConsumptionTierType [0..1] Bit 4 - isDER + currency: CurrencyCode [0..1] Bit 5 - isRevenueQuality + dataQualifier: DataQualifierType [0..1] notes 0..* Bit 6 - isDC + flowDirection: FlowDirectionType [0..1] Service kind Bit 7-16 - Reserved + intervalLength: duration [0..1] 0 - electricity Interv alBlock + kind: KindType [0..1] 1 - gas - interval: DateTimeInterval [0..1] + phase: PhaseCode [0..1] 2 - water status + powerOfTenMultiplier: PowerOfTenMultiplierType [0..1] 4 - pressure Specifies the current + timeAttribute: TimeAttributeType [0..1] 5 - heat status of this usage + tou: TOUType [0..1] 6 - cold point. + uom: UomType [0..1] 7 - communication 0 = off 8 - time 1 = on 0..* 0..*

IdentifiedObject IdentifiedObject Reading Interv alReading + timeStamp: TimeType + interval: DateTimeInterval [0..1] + value: UInt48 + value: UInt48

0..* 0..*

ReadingQuality

+ quality: QualityOfReading

3529 3530 3531 Table 13-4: URI Structure Table for Meter Mirroring. URI - Purpose GET PUT POST DELETE http{s}://{Host1} /mup Mirror Usage point (metering) resource O N/A M N/A list. Devices implementing the /mup (sub meter resource may support multiple instances to post its of meter mirror asset. instance record)

121

November, 2011 Draft ZigBee-11167

/mup/{#} Mirror Usage point instance including N/A N/A M O resources it supports. To write A additional mirrored data to the meter can mirroring delete its server. mirrored (Should instance only be on accepted mirroring if it is host. from the creator of the mirror)

3532 M – Mandatory 3533 O – Optional 3534 N/A – Not applicable 3535 POSTing a new mirror request. 3536 The following is an example of the initial POST for creating a metering mirror on a meter mirroring 3537 server. Note that in this example the initial POST also includes the first set of data to populate the mirror. 3538 The client would send: 3539 POST /mup HTTP/1.1 3540 3541 Host:{host} 3542 Content-Type: application/exi 3543 Content-Length: {length} 3544 3545 3546 3547 0x1234 3548 0x13 3549 ”321 876 2345” 3550 1 3551 3552 1 3553 Gas Meter 1234 Summation 3554 3555 9 3556 7 3557 0 3558 3559 3560 {time of reading} 3561 743527 3562 3563 3564 3565 2 3566 Gas Meter 1234 Intervals 122

November, 2011 Draft ZigBee-11167

3567 3568 4 3569 7 3570 3600 3571 0 3572 3573 3574 3575 { time of first interval } 3576 {interval duration} 3577 3578 3579 74 3580 3581 3582 75 3583 3584 3585 78 3586 3587 3588 82 3589 3590 3591 80 3592 3593 3594 75 3595 3596 3597 70 3598 3599 3600 71 3601 3602 3603 65 3604 3605 3606 66 3607 3608 3609 64 3610 3611 3612 65 3613 3614 3615 3616 3617 3618 Assuming that the server successfully created the mirror. 3619 The server would respond: 3620 3621 HTTP/1.1 201 Created 3622 Location: http{s}://{host}/mup/3 3623 3624 3625 Once the mirror has been created, new data can be added to the mirror with a single POST to the resource 3626 created by the initial POST.

123

November, 2011 Draft ZigBee-11167

3627 The client would send: 3628 POST /mup/3 HTTP/1.1 3629 3630 Host:{host} 3631 Content-Type: application/exi 3632 Content-Length: {length} 3633 3634 3635 3636 1 3637 3638 {time of reading} 3639 743527 3640 3641 3642 3643 2 3644 3645 3646 {time of first interval}{ 3647 {interval duration}{ 3648 3649 3650 74 3651 3652 3653 75 3654 3655 3656 78 3657 3658 3659 82 3660 3661 3662 80 3663 3664 3665 75 3666 3667 3668 70 3669 3670 3671 71 3672 3673 3674 65 3675 3676 3677 66 3678 3679 3680 64 3681 3682 3683 65 3684 3685 3686 3687 3688 3689 The server would rRespond: 124

November, 2011 Draft ZigBee-11167

3690 HTTP/1.1 201 Created 3691 3692 13.3.4.3 Subscription / Notification Behavior 3693 Subscription support is RECOMMENDED on the UsagePoint List and the MeterReading List. 3694 Subscription SHALL NOT be supported on the Reading and Interval Reading lists as that would flood 3695 the network. 3696 13.3.4.4 Application Guidelines / Behavior 3697 Application guidelines are listed in the Sections below. 3698 13.3.4.4.1 Meter Reading Types 3699 Meter reading is defined based on reading type. A reading type is constructed based on IEC CIM 3700 ReadingType class which contains a list of attributes (See Tables 11-7 thru 11-10 below). Only relevant 3701 CIM fields are listed in this document. More detailed information on IEC CIM ReadingType can be found 3702 in IEC 61968-9 Annex C. Note: It may be beneficial for implementers to obtain a copy of this document 3703 in order to better understand the meanings and uses of the IEC CIM Reading Types. 3704 A combination of the fields defines a unique reading type. For example, a reading type of 3705 CurrentSummationDelivered is made of the fields defined in the table below.

125

November, 2011 Draft ZigBee-11167

3706 Table 13-5: Reading Information Types.

SEP Reading Name T Accum Flow O Pow Data Time ulation U Consu er Of U Dire Phas Quali Commodity Kind / mptio Ten O Attribute Behavi ctio e fier C n Tier Mult M our n P iplier P CurrentSummationDel 15 1 1 1 12 (value 3 72 ivered (Present) (BulkQ (For (ElectricitySeco (Ene based (k) (W uantity) ward ndaryMetered) rgy) on h) ) Phase Code in the enume ration Figure ) CurrentSummationRec 15 1 19 1 12 3 72 eived (Present) (BulkQ (Rev (ElectricitySeco (Ene (k) (W uantity) erse) ndaryMetered) rgy) h) CurrentMaxDemandD 15 8 6 1 1 8 3 38 elivered (Present) (Maxi (Indicati (For (ElectricitySeco (De (k) (W mum) ng) ward ndaryMetered) man ) ) d) CurrentMaxDemandR 15 8 6 19 1 8 3 38 eceived (Present) (Maxi (Indicati (Rev (ElectricitySeco (De (k) (W mum) ng) erse) ndaryMetered) man ) d) CurrentBlockPeriodCo 32 1 1 1 12 (specifi 3 72 nsumptionDelivered (ForTheSpecif (BulkQ (For (ElectricitySeco (Ene ed (k) (W iedPeriod) uantity) ward ndaryMetered) rgy) block h) ) number ) Daily30MinutesFixed 79 4 1 1 12 3 72 BlockDelivered (Daily30minut (DeltaD (For (ElectricitySeco (Ene (k) (W eFixedBlock) ata) ward ndaryMetered) rgy) h) )

126

November, 2011 Draft ZigBee-11167

3707 Note that the reading types defined above apply to not only electricity metering data but also water and 3708 gas metering data. For example CurrentSummationDelivered can apply to gas or water if the 3709 commodity=”NaturalGas” or “PotableWater” with uom/index="m3" or “ccf”. Also a number of units of 3710 measure (UOMs) are supported such as kWh, kVAh and kVArh for electricity energy. 3711 Relevant UOMs are listed in the table below with enumerated values from IEC CIM 61968-9 Annex C: 3712 Table 13-6: Relevant UOMs.

Description Power of Ten Multiplier UOM A (Current) 0 5 V (Electric potential) 0 29 J (Energy joule) 0 31 kW (kilo-Watts) 3 38 m3 (Cubic Meter) 0 42 kVA (Apparent power) 3 61 kVAr (Reactive power) 3 63 Cosθ (Power factor) 0 65 V² (Volts squared) 0 67 A² (Amp squared) 0 69 kVAh (Apparent energy) 3 71 kWh (kilo-WattHours) 3 72 kVArh (Reactive energy) 3 73 ft3 (Cubic Feet) 0 119 ft3/h (Cubic Feet per Hour) 0 122 ccf ((100 or Centum) Cubic Feet) 2 119 ccf/h ((100 or Centum) Cubic Feet per Hour 2 122 m3/h (Cubic Meter per Hour) 0 125 US gl (US Gallons) 0 128 US gl/h (US Gallons per Hour) 0 129 IMP gl (Imperial Gallons) 0 130 IMP gl/h (Imperial Gallons per Hour) 0 131 BTU 0 132 BTU/h 0 133 Therm (100,000 BTU) 5 132 Liter 0 134 L/h (Liters per Hour) 0 137 kPA(gauge) 3 140 kPA(absolute) 3 155 3713 3714 All fields in Table -11-8 are enumerated (see diagram) based on IEC 61968-9 Annex C & D.

127

November, 2011 Draft ZigBee-11167

3715

3716 3717 Figure 13.3-2: Enumerated ReadingType fields and Quality Codes. 3718 The following XML is an example message payload of CurrentSummationDelivered meter reading type: 3719 3720 3721 1 3722 1 3723 1 3724 12 3725 128 3726 15 3727 3 3728 72 3729 3730 3731 Note that the meanings of the values populated in the XML can be found in the Table 11-8, row 1. 3732 3733 The ReadingType attributes are enumerated with numbers as shown above. 3734 3735 For convenience, a few previously defined SEP 1.x Reading Names can be derived as below: 3736  DFTSummation = CurrentSummationDelivered row with Reading/timeStamp = DailyFreezeTime

3737  ReadingSnapShotTime = Reading/timeStamp when the last time CurrentSummationDelivered, 3738 CurrentSummationReceived, CurrentMaxDemandDelivered, or CurrentMaxDemandReceived were 3739 captured

128

November, 2011 Draft ZigBee-11167

3740  CurrentMaxDemandDeliveredTime = Reading/timeStamp when CurrentMaxDemandDelivered was 3741 captured

3742  CurrentMaxDemandReceivedTime = Reading/timeStamp when CurrentMaxDemandReceived was 3743 captured

3744 TOU Information 3745 TOU tier summation reading types are summarized in the table below. 3746 Table 13-7: TOU Reading Types.

SEP Reading Name Power Time Accumula Flow TOU Of Ten UO tion Commodity Kind / Phase Attrib Directi Multipl M CPP ute Behaviour on ier 15 9 1 1 12 1 (value 3 72 CurrentTier1SummationD (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou based on (k) (Wh elivered t) n) d) Metered) gy) A) PhaseCo ) de in the enumerat ion Figure) 15 9 19 1 12 1 3 72 CurrentTier1SummationR (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh eceived t) n) e) Metered) gy) A) ) 15 9 1 1 12 2 3 72 CurrentTier2SummationD (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou (k) (Wh elivered t) n) d) Metered) gy) B) ) 15 9 19 1 12 2 3 72 CurrentTier2SummationR (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh eceived t) n) e) Metered) gy) B) ) 15 9 1 1 12 3 3 72 CurrentTier3SummationD (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou (k) (Wh elivered t) n) d) Metered) gy) C) ) 15 9 19 1 12 3 3 72 CurrentTier3SummationR (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh eceived t) n) e) Metered) gy) C) ) 15 9 1 1 12 4 3 72 CurrentTier4SummationD (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou (k) (Wh elivered t) n) d) Metered) gy) D) ) 15 9 19 1 12 4 3 72 CurrentTier4SummationR (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh eceived t) n) e) Metered) gy) D) ) 15 9 1 1 12 5 3 72 CurrentTier5SummationD (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou (k) (Wh elivered t) n) d) Metered) gy) E) ) 15 9 19 1 12 5 3 72 CurrentTier5SummationR (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh eceived t) n) e) Metered) gy) E) ) 15 9 1 1 12 6 3 72 CurrentTier6SummationD (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou (k) (Wh elivered t) n) d) Metered) gy) F) ) 15 9 19 1 12 6 3 72 CurrentTier6SummationR (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh eceived t) n) e) Metered) gy) F) )

129

November, 2011 Draft ZigBee-11167

SEP Reading Name Power Time Accumula Flow TOU Of Ten UO tion Commodity Kind / Phase Attrib Directi Multipl M CPP ute Behaviour on ier 15 9 1 1 12 7 3 72 CurrentTier7SummationD (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou (k) (Wh elivered t) n) d) Metered) gy) G) ) 15 9 19 1 12 7 3 72 CurrentTier7SummationR (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh eceived t) n) e) Metered) gy) G) ) 15 9 1 1 12 8 3 72 CurrentTier8SummationD (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou (k) (Wh elivered t) n) d) Metered) gy) H) ) 15 9 19 1 12 8 3 72 CurrentTier8SummationR (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh eceived t) n) e) Metered) gy) H) ) 15 9 1 1 12 9 3 72 CurrentTier9SummationD (Presen (Summatio (Forwar (ElectricitySecondary (Ener (TouI (k) (Wh elivered t) n) d) Metered) gy) ) ) 15 9 19 1 12 9 3 72 CurrentTier9SummationR (Presen (Summatio (Revers (ElectricitySecondary (Ener (TouI (k) (Wh eceived t) n) e) Metered) gy) ) ) 15 9 1 1 12 10 3 72 CurrentTier10Summation (Presen (Summatio (Forwar (ElectricitySecondary (Ener (TouJ (k) (Wh Delivered t) n) d) Metered) gy) ) ) 15 9 19 1 12 10 3 72 CurrentTier10Summation (Presen (Summatio (Revers (ElectricitySecondary (Ener (TouJ (k) (Wh Received t) n) e) Metered) gy) ) ) 15 9 1 1 12 11 3 72 CurrentTier11Summation (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou (k) (Wh Delivered t) n) d) Metered) gy) K) ) 15 9 19 1 12 11 3 72 CurrentTier11Summation (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh Received t) n) e) Metered) gy) K) ) 15 9 1 1 12 12 3 72 CurrentTier12Summation (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou (k) (Wh Delivered t) n) d) Metered) gy) L) ) 15 9 19 1 12 12 3 72 CurrentTier12Summation (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh Received t) n) e) Metered) gy) L) ) 15 9 1 1 12 13 3 72 CurrentTier13Summation (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou (k) (Wh Delivered t) n) d) Metered) gy) M) ) 15 9 19 1 12 13 3 72 CurrentTier13Summation (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh Received t) n) e) Metered) gy) M) ) 15 9 1 1 12 14 3 72 CurrentTier14Summation (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou (k) (Wh Delivered t) n) d) Metered) gy) N) ) 15 9 19 1 12 14 3 72 CurrentTier14Summation (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh Received t) n) e) Metered) gy) N) ) 15 9 1 1 12 15 3 72 CurrentTier15Summation (Presen (Summatio (Forwar (ElectricitySecondary (Ener (Tou (k) (Wh Delivered t) n) d) Metered) gy) O) )

130

November, 2011 Draft ZigBee-11167

SEP Reading Name Power Time Accumula Flow TOU Of Ten UO tion Commodity Kind / Phase Attrib Directi Multipl M CPP ute Behaviour on ier 15 9 19 1 12 15 3 72 CurrentTier15Summation (Presen (Summatio (Revers (ElectricitySecondary (Ener (Tou (k) (Wh Received t) n) e) Metered) gy) O) ) 3747 3748 Note the reading types defined above apply to not only electricity metering data but also water and gas 3749 metering data such as CurrentSummationDelivered can apply to gas or water if the kind="Gas" or 3750 “Water” with uom="m3" or “ccf”. 3751 A reading type name MAY include a unit name such as CurrentSummationDeliveredkWh or 3752 CurrentSummationDeliveredkVAh.

3753 TOU and Block Information 3754 TOU and block summation reading types are summarized in the table below. 3755 Table 13-8: TOU and Block Reading Types.

SEP Reading Name Accumu Powe Time Flow TO r Of lation Consumpt UO Attri Direc Commodity Kind U / Phase Ten Behavio ion Tier M bute tion CPP Multi ur plier 15 9 1 1 12 Consumptio (value 3 72 CurrentNoTierBlock1Sum (Prese (Summati (Forw (ElectricitySecond (Ene nTier1 based (k) (W mationDelivered nt) on) ard) aryMetered) rgy) on h) PhaseC ode in the enumer ation Figure) 15 9 1 1 12 Consumptio 3 72 CurrentNoTierBlock2Sum (Prese (Summati (Forw (ElectricitySecond (Ene nTier2 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) h) 15 9 1 1 12 Consumptio 3 72 CurrentNoTierBlock3Sum (Prese (Summati (Forw (ElectricitySecond (Ene nTier3 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) h) 15 9 1 1 12 Consumptio 3 72 … (Prese (Summati (Forw (ElectricitySecond (Ene nTierN (k) (W CurrentNoTierBlockNSum nt) on) ard) aryMetered) rgy) h) mationDelivered N=4..15 15 9 1 1 12 Consumptio 3 72 CurrentNoTierBlock16Su (Prese (Summati (Forw (ElectricitySecond (Ene nTier16 (k) (W mmationDelivered nt) on) ard) aryMetered) rgy) h) 15 9 1 1 12 1 Consumptio 3 72 CurrentTier1Block1Summ (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W ationDelivered nt) on) ard) aryMetered) rgy) A) h) 15 9 1 1 12 1 Consumptio 3 72 CurrentTier1Block2Summ (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier2 (k) (W ationDelivered nt) on) ard) aryMetered) rgy) A) h) 15 9 1 1 12 1 Consumptio 3 72 CurrentTier1Block3Summ (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier3 (k) (W ationDelivered nt) on) ard) aryMetered) rgy) A) h)

131

November, 2011 Draft ZigBee-11167

SEP Reading Name Accumu Powe Time Flow TO r Of lation Consumpt UO Attri Direc Commodity Kind U / Phase Ten Behavio ion Tier M bute tion CPP Multi ur plier 15 9 1 1 12 1 Consumptio 3 72 CurrentTier1BlockNSumm (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W ationDelivered … nt) on) ard) aryMetered) rgy) A) h) N=4..15 15 9 1 1 12 1 Consumptio 3 72 CurrentTier1Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) A) h) 15 9 1 1 12 2 Consumptio 3 72 CurrentTier2Block1Summ (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W ationDelivered nt) on) ard) aryMetered) rgy) B) h) 15 9 1 1 12 2 Consumptio 3 72 CurrentTier2BlockNSumm (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W ationDelivered … nt) on) ard) aryMetered) rgy) B) h) N=2..15 15 9 1 1 12 2 Consumptio 3 72 CurrentTier2Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) B) h) 15 9 1 1 12 3 Consumptio 3 72 CurrentTier3Block1Summ (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W ationDelivered nt) on) ard) aryMetered) rgy) C) h) 15 9 1 1 12 3 Consumptio 3 72 CurrentTier3BlockNSumm (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W ationDelivered … nt) on) ard) aryMetered) rgy) C) h) N=2..15 15 9 1 1 12 3 Consumptio 3 72 CurrentTier3Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) C) h) 15 9 1 1 12 4 Consumptio 3 72 CurrentTier4Block1Summ (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W ationDelivered nt) on) ard) aryMetered) rgy) D) h) 15 9 1 1 12 4 Consumptio 3 72 CurrentTier4BlockNSumm (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W ationDelivered … nt) on) ard) aryMetered) rgy) D) h) N=2..15 15 9 1 1 12 4 Consumptio 3 72 CurrentTier4Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) D) h) 15 9 1 1 12 5 Consumptio 3 72 CurrentTier5Block1Summ (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W ationDelivered nt) on) ard) aryMetered) rgy) E) h) 15 9 1 1 12 5 Consumptio 3 72 CurrentTier5BlockNSumm (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W ationDelivered … nt) on) ard) aryMetered) rgy) E) h) N=2..15 15 9 1 1 12 5 Consumptio 3 72 CurrentTier5Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) E) h) 15 9 1 1 12 6 Consumptio 3 72 CurrentTier6Block1Summ (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W ationDelivered nt) on) ard) aryMetered) rgy) F) h) 15 9 1 1 12 6 Consumptio 3 72 CurrentTier6BlockNSumm (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W ationDelivered … nt) on) ard) aryMetered) rgy) F) h) 132

November, 2011 Draft ZigBee-11167

SEP Reading Name Accumu Powe Time Flow TO r Of lation Consumpt UO Attri Direc Commodity Kind U / Phase Ten Behavio ion Tier M bute tion CPP Multi ur plier N=2..15 15 9 1 1 12 6 Consumptio 3 72 CurrentTier6Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) F) h) 15 9 1 1 12 7 Consumptio 3 72 CurrentTier7Block1Summ (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W ationDelivered nt) on) ard) aryMetered) rgy) G) h) 15 9 1 1 12 7 Consumptio 3 72 CurrentTier7BlockNSumm (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W ationDelivered … nt) on) ard) aryMetered) rgy) G) h) N=2..15 15 9 1 1 12 7 Consumptio 3 72 CurrentTier7Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) G) h) 15 9 1 1 12 8 Consumptio 3 72 CurrentTier8Block1Summ (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W ationDelivered nt) on) ard) aryMetered) rgy) H) h) 15 9 1 1 12 8 Consumptio 3 72 CurrentTier8BlockNSumm (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W ationDelivered … nt) on) ard) aryMetered) rgy) H) h) N=2..15 15 9 1 1 12 8 Consumptio 3 72 CurrentTier8Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) H) h) 15 9 1 1 12 9 Consumptio 3 72 CurrentTier9Block1Summ (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W ationDelivered nt) on) ard) aryMetered) rgy) I) h) 15 9 1 1 12 9 Consumptio 3 72 CurrentTier9BlockNSumm (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W ationDelivered … nt) on) ard) aryMetered) rgy) I) h) N=2..15 15 9 1 1 12 9 Consumptio 3 72 CurrentTier9Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) I) h) 15 9 1 1 12 10 Consumptio 3 72 CurrentTier10Block1Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) J) h) 15 9 1 1 12 10 Consumptio 3 72 CurrentTier10BlockNSum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W mationDelivered … nt) on) ard) aryMetered) rgy) J) h) N=2..15 15 9 1 1 12 10 Consumptio 3 72 CurrentTier10Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) J) h) 15 9 1 1 12 11 Consumptio 3 72 CurrentTier11Block1Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) K) h) 15 9 1 1 12 11 Consumptio 3 72 CurrentTier11BlockNSum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W mationDelivered … nt) on) ard) aryMetered) rgy) K) h) N=2..15 15 9 1 1 12 11 Consumptio 3 72 CurrentTier11Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou (W 133

November, 2011 Draft ZigBee-11167

SEP Reading Name Accumu Powe Time Flow TO r Of lation Consumpt UO Attri Direc Commodity Kind U / Phase Ten Behavio ion Tier M bute tion CPP Multi ur plier

mationDelivered nt) on) ard) aryMetered) rgy) K) nTier16 (k) h) 15 9 1 1 12 12 Consumptio 3 72 CurrentTier12Block1Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) L) h) 15 9 1 1 12 12 Consumptio 3 72 CurrentTier12BlockNSum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W mationDelivered … nt) on) ard) aryMetered) rgy) L) h) N=2..15 15 9 1 1 12 12 Consumptio 3 72 CurrentTier12Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) L) h) 15 9 1 1 12 13 Consumptio 3 72 CurrentTier13Block1Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) M) h) 15 9 1 1 12 13 Consumptio 3 72 CurrentTier13BlockNSum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W mationDelivered … nt) on) ard) aryMetered) rgy) M) h) N=2..15 15 9 1 1 12 13 Consumptio 3 72 CurrentTier13Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) M) h) 15 9 1 1 12 14 Consumptio 3 72 CurrentTier14Block1Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) N) h) 15 9 1 1 12 14 Consumptio 3 72 CurrentTier14BlockNSum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W mationDelivered … nt) on) ard) aryMetered) rgy) N) h) N=2..15 15 9 1 1 12 14 Consumptio 3 72 CurrentTier14Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) N) h) 15 9 1 1 12 15 Consumptio 3 72 CurrentTier15Block1Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier1 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) O) h) 15 9 1 1 12 15 Consumptio 3 72 CurrentTier15BlockNSum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTierN (k) (W mationDelivered … nt) on) ard) aryMetered) rgy) O) h) N=2..15 15 9 1 1 12 15 Consumptio 3 72 CurrentTier15Block16Sum (Prese (Summati (Forw (ElectricitySecond (Ene (Tou nTier16 (k) (W mationDelivered nt) on) ard) aryMetered) rgy) O) h)

3756

134

November, 2011 Draft ZigBee-11167

3757 13.4 Pricing Function Set 3758 13.4.1 Overview 3759 The pricing function set provides the tariff structures supplied to the ESI from the commodity service 3760 provider. 3761 The Pricing function set is designed to support a variety of tariff types: 3762 - Flat-rate pricing

3763 - Time-of-Use blocks

3764 - Consumption blocks

3765 - Hourly day-ahead pricing

3766 - Real-time pricing

3767 - Combinations of the above.

3768 Pricing Function Set supports application-specific tariffs for devices (e.g., PEV, DER), and special 3769 event-based prices like critical peak price (CPP). 3770 Pricing Function Set is designed to stand on its own but can be paired with Metering and Billing 3771 function sets to provide additional benefit to users. The Pricing Function Set is not intended to provide 3772 all the information necessary to represent a premises’ bill. 3773 13.4.2 Dependencies 3774 Pricing Function Set requires that a server implementing the base function set be present in the HAN. 3775 Most deployments will also require the Metering function set in order to match the price to a measured 3776 quantity of a commodity and provide meaningful information for most users. 3777 13.4.3 Sequence Diagrams 3778 At this time, there are no complex sequence diagrams needing detailing. 3779 13.4.4 URI Structure and Actions 3780 13.4.4.1 URI Structure 3781 Table 13-9: URI Structure Table for the Pricing Function Set Resources. URI – Assume all URIs Purpose GET PUT POS DELE begin with “http(s)://{ip T TE address}” /tp List of TariffProfile instances. M O O O /tp/{#} Specific TariffProfile instance. Allows M O O O clients to obtain information about the rate code. /tp/{#}/rc List of RateComponent instances. This M O O O list specifies a rate-specific container for the charges associated with a specific ReadingType, also referenced by the Metering function set.

135

November, 2011 Draft ZigBee-11167

/tp/{#}/rc/{#} Specific RateComponent instance. M O O O Includes link(s) to the list of TimeTariffIntervals that apply to referenced ReadingType for the RateComponent instance. /tp/{#}/rc/{#}/rt List of ReadingType instances. Specifies M O O O the types of readings associated with the TariffProfile charges, also referenced by the Metering function set implementation. /tp/{#}/rc/{#}/rt/{#} Specific ReadingType instance reference. M O O O /tp/{#}/rc/{#}/tti Collection of TimeTariffInterval M O O O instances, including associated ConsumptionTariffInterval and Cost. /tp/{#}/rc/{#}/tti/{#} Specific TimeTariffInterval instance that M O O O represents a unique usage interval and associated charges for the premises. /tp/{#}/acttti The active TimeTariffInterval instance(s) M O O O for a particular TariffProfile.

3782 3783 13.4.4.2 URI Actions 3784 3785 In order to obtain a particular TariffProfile instance.

3786 The client would send: 3787 GET /tp/1 HTTP/1.1 3788 Host: {Host1} 3789 The server would respond: 3790 HTTP/1.1 200 OK 3791 Content-Type: application/xml 3792 3793 3794 3796 TOU-R1 3797 3798 3799 3800 To obtain a particular RateComponent instance. 3801 The client would send: 3802 GET /tp/1/rc/0 HTTP/1.1 3803 Host: {Host1} 3804 3805 The server would respond: 3806 HTTP/1.1 200 OK 3807 Content-Type: application/xml 3808 3809 3810 136

November, 2011 Draft ZigBee-11167

3812 3813 400 3814 3815 3816 3817 To obtain a specific TimeTariffInterval instance. 3818 The client would send: 3819 GET /tp/1/rc/0/tti/34 HTTP/1.1 3820 Host: {Host1} 3821 The server would respond: 3822 HTTP/1.1 200 OK 3823 Content-Type: application/xml 3824 3825 3826 3827 3830 3831 3832 1 3833 0 3834 3835 3 3836 0 3837 3838 3839 14400 3840 1325376000 3841 60 3842 60 3843 3844 false 3845 6 3846 3 3847 3848 13.4.5 Subscription / Notification Behavior 3849 It is RECOMMENDED that servers and clients support subscription of the following resources: 3850 - /tp

3851 Allows a client to be informed of updates to the TariffProfile instances posted on the server. 3852 - /tp/{#}/rc/{#}/tti

3853 Allows a client to get updates on the time and consumption tariff intervals as they are made 3854 available. 3855 13.4.6 Paging List Ordering 3856 For paging purposes, TimeTariffInterval instances SHALL be ordered based on the following criteria: 3857 1. IsActive where those instances whose IsActive attribute equals TRUE are listed before those 3858 which are FALSE.

3859 2. RandomizedDateTimeInterval where the instances with the earliest possible Effective Start Time 3860 are listed before those with a later Effective Start Time.

137

November, 2011 Draft ZigBee-11167

3861 13.4.7 Application Guidelines / Behavior 3862 13.4.7.1 TariffProfile 3863 TariffProfile is the first resource in the Pricing hierarchy. It is linked to the Metering function set to 3864 provide the ability to associate charges for a commodity measured at a specific metering usage point 3865 (e.g., premises water, electric, or gas meter, PEV or DER sub-meter). In this way, Pricing information 3866 can be unique to a specific device or class of devices. 3867 Servers and Clients implementing the Pricing function set MUST be capable of internally storing and 3868 supporting at least one TariffProfile instance. 3869 13.4.7.1.1 Description 3870 Supplied by the Pricing service provider. This value would typically be displayed to a user to 3871 communicate the name of the current billing period (e.g., November 2010, Nov-Dec 2010). 3872 13.4.7.1.2 Rate Code 3873 Provided by the Pricing service provider per its internal business needs and practices and provides a 3874 method to identify the specific rate code for the TariffProfile instance. This would typically not be 3875 communicated to the user except to facilitate troubleshooting due to its service provider-specific 3876 technical nature. 3877 13.4.7.2 Rate Component 3878 Provides the ability to describe the ReadingType instance and the associated TimeTariffInterval 3879 instances for a particular BillingPeriod. This is most easily thought of as a container that allows a 3880 particular ReadingType to be matched with its appropriate TimeTariffInterval instances. 3881 RateComponent has an OPTIONAL Description attribute that can be used to provide additional 3882 information. 3883 Servers SHALL support at least two RateComponent instances for each TariffProfile. 3884 Clients SHALL support at least one RateComponent instance for each TariffProfile. Clients 3885 implementing this resource MAY support multiple instances of RateComponent, e.g. to convey prices 3886 for forward energy (consumed by premises) and reverse energy (supplied by premises). 3887 13.4.7.2.1 Description 3888 Supplied by the Pricing service provider. This value would typically be displayed to a user to 3889 communicate the human-readable description of the rate component (e.g., Energy consumption, Demand 3890 portion). 3891 13.4.7.2.2 powerLimit 3892 Indicates the power component for the applicable rate. powerLimit is used to communicate the 3893 instantaneous demand limit for the rate (e.g., 20 kW) over which additional charges, penalties, or tariff 3894 changes MAY apply. Demand limits are typically a component of commercial and industrial tariff 3895 structures. It could also be used to facilitate PEV-specific demand limits in the context of fast charging. 3896 For premises with distributed energy resources, powerLimit can be used to communicate the tariff’s 3897 instantaneous supply limit over which additional incentives will not be provided to the account holder or 3898 over which penalties MAY apply. 3899 Representations of demand averages or peaks over the billing period for the purposes of calculating a 3900 bill are not supported for this release of Smart Energy Profile. 3901 13.4.7.3 Reading Type 3902 Indicates the commodity measurement type that applies for the applicable RateComponent. This 3903 provides the ability to reference the multiple facets of a tariff profile (e.g., energy consumed, energy

138

November, 2011 Draft ZigBee-11167

3904 supplied, kVARs consumed, kVARs provided, demand) to the measurement point in the HAN where 3905 these components are measured. A RateComponent can only have one ReadingType instance. 3906 See the Metering function set for more detail on the ReadingType object and its associated attributes. 3907 13.4.7.4 TimeTariffInterval 3908 Describes the time-differentiated portion of the rate, if applicable, and provides the ability to specify 3909 multiple time intervals, each with its own ConsumptionTariffInterval, price, and Cost. Rates that do not 3910 contain time-differentiated characteristics MUST create one TimeTariffInterval instance with a 3911 RandomizedDateTimeInterval of sufficient duration to cover at least the next 24 hours, though 3912 specifying a time in the very far future could minimize communications on the HAN and back haul 3913 networks. 3914 Client shall support a minimum of two TimeTariffInterval instances for one ReadingType instance 3915 (i.e., the active and subsequent TimeTariffInterval instance for a ReadingType, probably kWh). Client 3916 SHOULD support 48 TimeTariffInterval instances for at least one ReadingType instance. Servers 3917 SHALL, at a minimum, provide clients the TimeTariffInterval instances necessary to cover the next 24 3918 hours, which is important to facilitate HAN devices in managing their daily operations. The collection 3919 of TimeTariffInterval instances SHALL be a time ordered list, where instances with the earliest 3920 scheduled start time will be first in the list. Servers are responsible for maintaining TimeTariffInterval 3921 instances in their list for the duration of the instance, including the maximum start and end 3922 randomization specified. Servers are also responsible for removing instances from their list that have 3923 expired, have been removed by the service provider, or whose Effective End Time has passed. Servers 3924 are responsible for selecting which events to remove to make room for new ones. 3925 Clients SHALL be capable of internally storing and supporting at least one instance of 3926 TimeTariffInterval for each ReadingType. It is RECOMMENDED that client devices be capable of 3927 internally storing and supporting a pricing schedule for the next 24 hours. When clients do not see a 3928 TimeTariffInterval instance in the server’s list that they previously retrieved, they should not assume the 3929 instance has been canceled, but simply that is has been removed. Clients should not treat the previous 3930 retrieval as valid and wait for it to reappear on the server or be replaced by a new instance. 3931 A TimeTariffInterval instance SHALL be considered active and included in the servers currently active 3932 TimeTariffInterval resource /acttti resource at the earliest possible Effective Start Time. 3933 The series of TimeTariffInterval instances on a server may contain gaps or breaks where price is not 3934 defined for some time period. This may occur for various reasons, such as when private information is 3935 cleared from the server (e.g., during move-out). Rules for handling these gaps are as follows: 3936 3937  If a client displays the active or scheduled price to the user, the client SHALL indicate the 3938 presence of an unexpected issue with the price data. 3939  If a client displays calculated instantaneous cost data to the user, the client SHALL indicate the 3940 presence of an unexpected issue with the price data. 3941  If a client displays calculated running or averaged cost data to the user, the client MAY 3942 continue to display values, by excluding the time periods where no price is defined. However, 3943 the client SHALL also indicate the presence of an unexpected issue with the price data for as 3944 long as there are price gaps during the time period the client uses to calculate these values. 3945  Clients SHALL NOT default to any hardcoded price (e.g., $0) or use price from another 3946 (past/future) TimeTariffInterval. 3947  If the pricing server later makes TimeTariffInterval instances available to fill pricing gaps, 3948 clients that display calculated cost information MAY recalculate past cost data based on the 3949 new information.

139

November, 2011 Draft ZigBee-11167

3950 Clients that are price responsive SHOULD return to normal operational mode during time periods where 3951 no TimeTariffInterval instance is defined. These clients SHOULD provide some notification to the user 3952 that 3953 The above guidelines promote common client behavior and reduce the chances of different 3954 implementations displaying different cost information to a user in the event pricing information is 3955 unavailable during a particular period. This could cause users to question the reliability of the data. 3956 13.4.7.4.1 Interval 3957 The interval object provides randomization parameters as well as start time and duration for the 3958 TimeTariffInterval. 3959 Randomization provides two signed attributes, randomizeEnd and randomizeStart. None, one, or both of 3960 these may be included as part of a TimeTariffInterval. 3961 While strongly RECOMMENDED, Pricing clients are NOT REQUIRED to follow the sign of 3962 randomization for Pricing function set messages. However, Pricing clients SHALL observe the absolute 3963 value of the randomizeEnd or randomizeStart value for the randomization range when calculating the 3964 randomization value. 3965 13.4.7.4.2 Is Active 3966 Determined by the server. Signals to clients which TimeTariffInterval instances are active at any given 3967 time. Instances SHALL be considered active at the earliest possible Effective Start Time. 3968 13.4.7.4.3 numPriceLevels 3969 Provided by the Pricing service provider, which may be the commodity provider or another Pricing 3970 server in the HAN (e.g., PEMS). In conjunction with PriceLevel, signals the relative scarcity of the 3971 commodity for the duration of the TimeTariffInterval instance (e.g., a relative price signal). This is 3972 useful in providing context for nominal price signals to consumers or devices unable to develop the 3973 relative scarcity of a price signal on their own. Please see SCE’s “Prices to Devices: Price Responsive 3974 Devices and the Smart Grid” white paper2 for additional background. 3975 If numPriceLevels is provided by the server, then PriceLevel SHALL also be provided by the server. 3976 numPriceLevels serves as a legend key and defines the total number of relative price levels that apply 3977 for all TimeTariffInterval instances of a given TarfiffProfile. For example, if a rate had three TOU tiers, 3978 numPriceLevels would be a value of “3.” Generally, numPriceLevels should be the same for all 3979 TimeTariffIntervals in a collection except in cases where the number of price tiers fluctuates (e.g., a flat 3980 rate or one tier price structure during the weekend and two-tier price structure on weekdays). 3981 numPriceLevels is defined in accordance with applicable regulatory rules or by a PEMS in the HAN that 3982 assumes pricing server responsibilities for devices it manages. A sophisticated PEMS could perform its 3983 own analysis of the nominal prices (e.g., price or Cost) received and publish an algorithmic-based 3984 numPriceLevels and PriceLevel combination to client devices. 3985 It is important for Pricing service providers to recognize the effect these signals have on client devices 3986 and to ensure that the numPriceLevels specified is actually the total number used. For example, a 3987 Pricing service provider is strongly discouraged from specifying numPriceLevels = 6 and then only 3988 using four PriceLevels (e.g., 1-4). This is not to discourage operators from having infrequently used 3989 (e.g., “critical”) price levels, but all levels indicated should be planned to be used at some point in the 3990 course of business operations.

2http://asset.sce.com/Documents/Environment%20- %20Smart%20Grid/PriceSignalsandPriceResponsiveDevices.pdf

140

November, 2011 Draft ZigBee-11167

3991 13.4.7.4.4 priceLevel 3992 Indicates the current or active relative price level for a specific TimeTariffInterval instance. In 3993 conjunction with numPriceLevels, this attribute informs a device of the current economic scarcity of 3994 consuming or producing a commodity (e.g., a high or low price period) for the duration of the specific 3995 TimeTariffInterval instance. 3996 If priceLevel is provided by the server, then numPriceLevels SHALL also be provided by the server. 3997 It is REQUIRED that numPriceLevels and priceLevel values ascend in order of scarcity, where 1 signals 3998 the lowest relative economic scarcity and higher values signal increasing relative economic scarcity. 3999 For example, if numPriceLevels is equal to “3,” then if the lowest relative priceLevel were equal to “1,” 4000 devices would assume this is the lowest relative price at which to operate. Likewise, if the priceLevel in 4001 the next TimeTariffInterval instance is equal to “2,” then the device would assume it was relatively more 4002 expensive to operate during this TimeTariffInterval instance than the previous one. 4003 There is no limit to the number of relative price levels other than that indicated in the attribute type, but 4004 practically speaking, service providers should strive for simplicity and recognize the diminishing returns 4005 derived from increasing the numPriceLevel values above four. 4006 13.4.7.4.5 ConsumptionTariffInterval 4007 Supports rate structures with inclining block consumption tiers whereby the commodity charges vary 4008 based on the overall quantity consumed over the course of the tariff cycle or billing period.

4009 13.4.7.4.5.1 Price 4010 Provides the monetary price that applies to the specified commodities. The currency associated with 4011 this price is determined by the currency attribute specified in the CustomerAccount object. It is up to the 4012 Pricing service provider to determine the appropriate amount to provide based on its applicable 4013 regulatory rules. For example, price could be net or inclusive of applicable taxes, fees, or levies. 4014 The Billing function set provides the ability to represent billing information in a more detailed manner.

4015 13.4.7.4.5.2 startValue 4016 Specifies the starting commodity measurement values at which the various ConsumptionTariffInterval 4017 instances begin. ConsumptionTariffInterval instances should be updated for each billing period as the 4018 new inclining block tier values become known. 4019 For example, in a rate structure with three inclining block tiers for electricity consumption, there would 4020 be three ConsumptionTariffInterval instances specified for each TimeTariffInterval. Each instance 4021 applies to consumption during the upcoming billing period from 0-100 kWh, 101-150 kWh, and 151- 4022 200 kWh. At the end of the previous billing period, the customer’s accumulated consumption value in 4023 the electricity meter was “24548.” Therefore, the startValues for upcoming ConsumptionTariffInterval 4024 instances would respectively be: 24648, 24698, and 24748. 4025 For tariffs that do not have consumption interval-based charges, a single ConsumptionTariffInterval 4026 SHALL be provided with startValue of “0” in order to reflect that there is only one 4027 ConsumptionTariffInterval in the tariff structure. 4028 13.4.7.4.6 Environmental Cost 4029 Provides alternative or secondary price information for the relevant ReadingType. The availability of 4030 the environmental price supports jurisdictions which seek to convey the environmental price per unit of 4031 the specified commodity not expressed in currency (e.g., environmental, renewable generation 4032 percentage).

4033 13.4.7.4.6.1 Amount 141

November, 2011 Draft ZigBee-11167

4034 The raw integer value of the Cost.

4035 13.4.7.4.6.2 Cost Kind 4036 The unit of measurement associated with the amount (e.g., grams of carbon dioxide). 4037 13.4.7.5 Sleepy Devices 4038 It is RECOMMENDED that sleepy client devices send requests to the server on a periodic basis. The 4039 RECOMMENDED time period for the periodic poll is no more than once per hour but at least once per 4040 24-hour period. This ensures the client a high likelihood of receiving the pricing information needed to 4041 manage its operations in a timely fashion. 4042 It is RECOMMENDED that sleepy client devices request updated information for pending 4043 TimeTariffInterval instances just prior to those TimeTariffInterval instances becoming active (e.g., 5-10 4044 minutes prior, including any negative randomizeStart). This ensures the TimeTariffInterval instance 4045 previously retrieved is still valid and accurate with the latest instance on the server.

4046 13.5 Messaging Function Set 4047 13.5.1 Overview 4048 This function set provides an interface for a text messaging service. Client devices of this function set 4049 include In Premises Displays and other text messaging display devices. Server devices of this function 4050 set include ESIs or a back office server, depending on system design. The response function set is used in 4051 conjunction with the messaging function set to allow client devices to confirm the viewing of messages 4052 and report advanced responses. 4053 Servers expose messages to client devices in the form of separate messaging URIs. Each messaging URI 4054 instance will contain information that a client device can use to display the message appropriately. For 4055 example, start time, duration of event, text to display, etc. 4056 13.5.2 Dependencies 4057 Messaging requires the following server resources be present in the HAN: 4058 - Base Function Set (e.g., time, …)

4059 - Enrollment

4060 - Response Function Set

4061 13.5.3 URI Structure and Actions 4062 13.5.3.1 URI Structure 4063 Table 11-12: URI Structure Table for the Messaging Resource. URI - Purpose GET PUT POST DELE http{s}://{Host1} TE /msg List of messaging collections. A M O O O message collection is a group of

messages that have some relation defined by the server provider. /msg/{#} Specific message collection resource. M O O O This representation MAY not contain

any attributes itself, per se, but rather

142

November, 2011 Draft ZigBee-11167

links to each of those attributes. /msg/{#}/txt Collection of text messages. Devices M O O O MAY support displaying multiple

messages to the user but are only REQUIRED to at least show one of the currently active messages of this list.

/msg/{#}/txt/{#} Specific Message resource. This M O O O resource can be thought of as a

particular Message valid for a period of time. /msg/{#}/txt/act Collection of Messages that are M O O O currently active.

4064 4065 For methods that are not allowed on particular URIs, a server is still REQUIRED to respond if a client 4066 attempts to instantiate one of the methods. An HTTP error response should be sent back, it is 4067 RECOMMENDED to use “Error Code 401 Unauthorized”. 4068 13.5.3.2 URI Actions 4069 Client and server requests and responses are listed below: 4070 The list of message collections URI is: 4071 http{s}://{Host1}/msg

4072 13.5.3.2.1.1 GET 4073 GET /msg returns a list (described by the schema) of message collections, each with their own URI that is 4074 subordinate to this URI. Note the XML data is example only. 4075 The client would send: 4076 GET /msg HTTP/1.1 4077 Host: {Host1} 4078 The server would respond: 4079 HTTP/1.1 200 OK 4080 Content-Type: application/xml 4081 4082 4083 4084 4085 4086 Neighborhood 1 4087 6161616161616160 4088 Message Collection 1 4089 4090 143

November, 2011 Draft ZigBee-11167

4091 4092 Neighborhood 2 4093 6161616161616161 4094 Message Collection 2 4095 4096 4097 4098 Neighborhood 3 4099 6161616161616162 4100 Message Collection 3 4101 4102 4103 4104 4105 The specific Message collection URI is: 4106 http{s}://{Host1}/msg/{#}

4107 13.5.3.2.1.2

4108 13.5.3.2.1.3 GET 4109 GET /msg/{#} returns a representation and link where this collection of messages can be found. Note the 4110 XML data is example only.

4111 The client would send: 4112 GET /msg/0 HTTP/1.1 4113 Host: {Host1} 4114 4115 The server would respond: 4116 HTTP/1.1 200 OK 4117 Content-Type: application/xml 4118 4119 4120 4121 4122 Neighborhood 1 4123 6161616161616160 4124 Message Collection 0 4125 4126 4127 The collection of messages URI is: 4128 4129 http{s}://{Host1}/msg/{#}/txt

4130 13.5.3.2.1.4 GET 4131 GET /msg/{#}/txt returns a list (described by the schema) of messages, each with their own URI that is 4132 subordinate to this URI. Note the XML data is example only.

4133 The client would send: 4134 GET /msg/0/txt HTTP/1.1 4135 Host: {Host1} 4136 4137 The server would respond: 4138 HTTP/1.1 200 OK 144

November, 2011 Draft ZigBee-11167

4139 Content-Type: application/xml 4140 4141 4142 4143 4144 4145 Neighborhood 1 4146 6161616161616160 4147 Message 1 4148 4149 4150 4151 Neighborhood 1 4152 6161616161616160 4153 Message 2 4154 4155 4156 4157 Neighborhood 1 4158 6161616161616160 4159 Message 3 4160 4161 4162 4163 Neighborhood 1 4164 6161616161616160 4165 Message 4 4166 4167 4168 The specific message URI is: 4169 http{s}://{Host1}/msg/{#}/txt/{#}

4170 13.5.3.2.1.5 GET 4171 GET /msg/{#}/txt/{#} returns XML data for this message (described by the schema). Note the XML data 4172 is example only. 4173 The client would send: 4174 GET /msg/0/txt/1 HTTP/1.1 4175 Host: {Host1} 4176 4177 The server would respond: 4178 HTTP/1.1 200 OK 4179 Content-Type: application/xml 4180 4181 4182 4183 4184 6161616161616161 4185 305419896 4186 FFFFFFFF 4187 4188 6400305419900 4190 4191 23 4192 Utility A 4193 2 4194 0 4195 This is a text message. 145

November, 2011 Draft ZigBee-11167

4196 4197 13.5.4 Subscription / Notification Behavior 4198 Messaging function set servers SHALL provide the ability for clients to subscribe to at least the following 4199 resources: 4200 - The list of Message collections

4201 - The collection of specific text Messages

4202 - The status resource within one Message

4203 - The active resource listing all active Messages

4204 Client devices can subscribe to the list of Message collections to be notified of any changes to the list. 4205 Servers SHALL notify subscribed clients at the moment that the change occurs on the list. 4206 Client devices can subscribe to a collection of specific text Messages under one particular messaging 4207 instance. Servers are responsible for notifying their subscribers at the moment a change occurs on the list. 4208 Client devices can subscribe to the Status resource of a specific Message instance to stay up to date on 4209 any changes to the event. When the client device discovers a new instance of a Message, it can subscribe 4210 to the Status resource of that instance to allow it to be notified of any changes. Servers are responsible for 4211 notifying their subscribers at the moment a change occurs to the Status resource of a Message instance. 4212 13.5.5 Application Guidelines / Behavior 4213 13.5.5.1 TextMessage 4214 A TextMessage object is used to provide control parameters to a messaging client. The deviceCategory 4215 attribute is used for service provider specific categorization of the message according to their corporate 4216 standards, practices, and existing IT systems (e.g. for management of assets, maintenance, work, outage, 4217 customers, etc.). A message will have a createdDateTime attribute which will indicate the date and time 4218 the Message was created. The StartTime and Duration of the Message is given in the DateTimeInterval 4219 object which will indicate how long the Message is intended to be displayed on a client. TextMessage 4220 SHALL have a unique identifier and SHALL NOT reuse a value until a rollover has been reached. The 4221 rollover value is determined from the attribute type and size found in the Schema. 4222 TextMessage object uses the responseRequired attribute which indicates whether or not this particular 4223 Message is requiring a response from the client. The Messaging function set supports the following 4224 responseRequired attribute values: no response is REQUIRED, end device SHALL indicate the message 4225 was received, end device SHALL indicate specific responses, and user response required. 4226 When the responseRequired attribute is equal to “1”: End device SHALL indicate the message received, 4227 then the client SHALL send a response StatusType of 0x01: Message received at the time the message is 4228 received by the client. 4229 If the response Required attribute is equal to “2”: End device SHALL indicate specific response, then the 4230 client MUST be capable of responding with the following response StatusType values; 0x01: Message 4231 received, 0x02: Event started, 0x03: Event completed, and 0x07: Event superseded. Response 4232 StatusType 0x07: Event superseded, should be used if the client has to remove a message from its display 4233 due to lack/shortage of resources and replaces this message with a higher priority message. 146

November, 2011 Draft ZigBee-11167

4234 When the responseRequired attribute is equal to “3”: User response is REQUIRED, the client should 4235 update the response StatusType with value 0x11: User confirmation, only when there is some user 4236 interaction to indicate the message has been read via a human machine interface. This confirmation 4237 should not be automatically generated by the client. 4238 The Originator attribute is a human-readable string that describes the Originator (e.g., the Messaging 4239 server or one of its agents), definable by the Messaging server and could be different for messages 4240 originating from different business groups or Messaging server 3rd-party partners (e.g., billing 4241 department, marketing department, 3rd-party messages). 4242 The Priority attribute is used to inform the client of the priority of the particular Message. Devices with 4243 constrained or limited resources for displaying Messages should use this attribute to determine how to 4244 handle displaying currently active Messages (e.g. if a device uses a scrolling method with a single 4245 Message viewable at a time it MAY want to push a low priority Message to background and bring a 4246 newly received high priority Message to the foreground). 4247 The textMessage attribute contains the actual UTF-8 encoded text to be displayed in conjunction with the 4248 messageLength attribute which contains the overall length of the textMessage attribute. Clients and 4249 servers are REQUIRED to support a minimum message length of 100 bytes. Messages that exceed this 4250 length will be left to the client to choose what method to handle the message (truncation, scrolling, etc.). 4251 13.5.5.2 DateTimeInterval 4252 DateTimeInterval provides two attributes, duration and start. 4253 The duration of the TextMessage is provided in seconds using the duration attribute. 4254 The start time for a TextMessage is provided using the start attribute, which is an unsigned 64 bit value 4255 representing the number of seconds since 0 hours, 0 minutes, 0 seconds, on the 1st of January, 1970. 4256 13.5.5.3 HANDeviceAssetCategoryType 4257 HANDeviceAssetCategoryType is used within a TextMessage to target a specific type of device. This 4258 attribute will indicate which type of device is being targeted. A TextMessage MAY target multiple 4259 HANDeviceAssetCategoryTypes. 4260 13.5.5.4 EndDeviceGroup 4261 EndDeviceGroup is used to group multiple HANDeviceAssets into one addressable collection, this allows 4262 for a Message to apply to more than one device. A Message MAY contain multiple EndDeviceGroups, 4263 when this is the case, each EndDeviceGroup instance SHALL include a unique identifier aside from the 4264 groupAddress. 4265 13.5.5.5 Status 4266 The Status Object used to indicate the current status of a Message. Devices can read this resource to get 4267 the most up to date status of the event. Device can also subscribe to this resource and get updates when 4268 there is a change. 4269 Devices that do not subscribe to this resource SHALL read it before executing an event that has been 4270 scheduled to occur in the future. These devices are also RECOMMENDED to read this resource every 5 4271 minutes while the event is active, this will allow them to be aware of any change during the event. 4272 The Messaging Function Set server is REQUIRED to provide the Status resource along with a 4273 subscription mechanism for this resource. When an event status changes, the server SHALL update this 147

November, 2011 Draft ZigBee-11167

4274 resource to indicate the new status, along with the time the new status became effective. The server 4275 SHALL notify all subscribers of a change to this resource. 4276 There are 3 specified types of status, they are described below. 4277 - Scheduled

4278 This status indicates that the event has been scheduled and no modification has occurred. The 4279 server SHALL set the event to this status when the event is first scheduled and persist until the 4280 event has begun or has been modified in any way. For Messages with a start time equal to the 4281 current time, this status SHALL never be indicated; the event SHALL start with a status of 4282 “Active”. 4283 - Active

4284 This status indicates that the event is currently active. The server SHALL set the event to this 4285 status when the event reaches its start time and persist until the event has completed or been 4286 cancelled.

4287 - Cancelled

4288 When a Message is cancelled, the dateTime attribute can be used to indicate the effective time of 4289 the cancellation. If a server would like to cancel the event immediately, it would provide a 4290 dateTime value with the current time. The server is responsible for maintaining the cancelled 4291 event in its collection for the duration of the original event.

4292 13.6 Billing Function Set 4293 13.6.1 Overview 4294 There are several resources that are used to support billing related functions. The billing function set 4295 provides consumption or costs, estimates of future consumption, and/or historical consumption from a 4296 service provider to an end device. In addition to consumption and costs that would be calculated by the 4297 back end systems and shared with the end devices, billing also provides a mechanism to allow the service 4298 provider to push down targets or challenges to help consumers manage their budgets. A target could be a 4299 percentage or fixed value of reduction – possibly chosen by the consumer- to meet within a defined time 4300 frame. 4301 13.6.1.1.1 TargetReading Resource 4302 The TargetReading Resource provides a way for a service provider to create challenges or targets for an 4303 end customer to try to achieve within a certain time frame. 4304 13.6.1.1.2 ProjectionReading Resource 4305 The ProjectionReading Resource provides a way for a service provider to provide future projected 4306 consumption or cost for a particular reading type calculated at the service provider backend. 4307 13.6.1.1.3 HistoricalReading Resource 4308 The HistoricalReading Resource provides a way for a service provider to provide historical consumption 4309 or cost for a particular reading type that is verified and possibly corrected at the service provider backend.

148

November, 2011 Draft ZigBee-11167

4310 13.6.1.1.4 CustomerAccount Resource 4311 The CustomerAccount resource contains information specific to the account such as the currency. The 4312 Customer Account is directly linked to a single Usage Point. 4313 13.6.1.1.5 BillingPeriod Resource 4314 A BillingPeriod relates to a timeframe that a commodity is billed on. There may be multiple 4315 BillingPeriods that relate to different TariffProfiles. 4316 13.6.1.1.6 Charge Resource 4317 A Charge is a line item on a bill (e.g., tax for the billing period) or a charge for a period of time (e.g., one 4318 day estimate). This could be a tax amount, commodity charge, delivery charge, or any other type of line 4319 item that could appear to the customer. 4320 13.6.2 Dependencies 4321 The Billing Function Set requires that there be a valid Tariff Profile defined for keeping a reference to the 4322 updated information that is pushed down from the backend systems. Without this dependency, the 4323 resource would only be able to house customer billing information and not provide consumption and 4324 billing synchronization with backend systems. 4325 - Base Function Set

4326 - Pricing Function Set

4327 - Metering Function Set

149

November, 2011 Draft ZigBee-11167

4328 13.6.3 Sequence Diagrams 4329 13.6.3.1.1 Billing Data

4330 4331 Figure 13.6-1: Billing Data.

150

November, 2011 Draft ZigBee-11167

4332 13.6.3.1.2 Billing Readings

4333 4334 Figure 13.6-2: Billing Readings. 4335 13.6.4 URI Structure and Actions 4336 The URI structure and actions provide a resource for devices to query for billing related information. 4337 From the SEP 2.0 HAN there would be no purpose to change or delete customer billing information that 4338 is created. The only updates and deletions done to these objects would come from the backend system 4339 and outside of the SEP 2.0 HAN. 4340 13.6.5 Customer Account Resource 4341 13.6.5.1 URI Structure 4342 Table 11-13 URI Structure Table URI Purpose //ca URI to the Customer Account information GET PUT POST DELETE M

4343 13.6.5.2 URI Actions 4344 The client would send: 4345 GET /billing/ca HTTP/1.1 4346 Host: {host} 151

November, 2011 Draft ZigBee-11167

4347 4348 The server would respond: 4349 HTTP/1.1 200 OK 4350 Content-Type: application/xml 4351 4352 4353 4355 299fb265a7629008 4356 Main 4357 946684800 4358 4359 4360 4361 4362 4363 65535 4364 4365 4366 4367 4368 13.6.6 BillingPeriod Resource 4369 13.6.6.1 URI Structure 4370 Table 13-10: URI Structure Table for Billing Period Resource. URI Purpose /billing/bp List of BillingPeriods GET PUT POST DELETE M /billing/bp/{#} Specific Billing Period information GET PUT POST DELETE M

4371 13.6.6.2 URI Actions 4372 The client would send: 4373 GET /billing/bp/1/HTTP/1.1 4374 Host: {host} 4375 4376 The server would respond: 4377 HTTP/1.1 200 OK 4378 Content-Type: application/xml 4379 4380 4381 4383 4384 2678400 4385 1325376000 4386 152

November, 2011 Draft ZigBee-11167

4387 4388 13.6.7 Charge Resource 4389 The URI structure of the Charge Resource is described in the Metering Section as MeterReading. All 4390 values and attributes are mapped to the MeterReading Object. For Charges, ReadingType.kind SHALL be 4391 “3”, representing currency, and ReadingType.currency SHALL be set appropriately. (e.g. “840” is “US 4392 Dollar”) 4393 13.6.7.1 URI Structure 4394 Table 13-11: URI Structure Table. URI Purpose /billing/ch List of Charges GET PUT POST DELETE M

4395 13.6.7.2 URI Actions 4396 TBD 4397 13.6.8 TargetReading Resource 4398 13.6.8.1 URI Structure 4399 The URI structure of the TargetReading Resource is described in the Metering Section as MeterReading. 4400 All values and attributes are mapped to the MeterReading Object. Typically, a single interval will be used 4401 to specify a billing period e.g., with “Summation” accumulation behavior, “for the period specified”. 4402 Table 13-12: URI Structure Table. URI Purpose /billing/tar URI to the top level list of targets. GET PUT POST DELETE M

4403 13.6.8.2 4404 13.6.8.3 URI Actions 4405 4406 13.6.9 ProjectionReading Resource 4407 The URI structure of the ProjectionReading Resource is described in the Metering section as 4408 MeterReading. All values and attributes are mapped to the MeterReading Object.

153

November, 2011 Draft ZigBee-11167

4409 13.6.9.1 URI Structure 4410 Table 13-13: URI Structure Table. URI Purpose /billing/pro URI to the top level list of projected readings. GET PUT POST DELETE M

4411 13.6.9.2 4412 13.6.9.3 URI Actions 4413 TBD 4414 13.6.10 HistoricalReading Resource 4415 13.6.10.1 URI Structure 4416 The URI structure of the HistoricalReading Resource is described in the Metering Section as 4417 MeterReading. All values and attributes are mapped to the MeterReading Object. 4418 Table 13-14: URI Structure Table. URI Purpose /billing/ver URI to the top level list of verified readings. GET PUT POST DELETE M

4419 4420 13.6.10.2 URI Actions 4421 TBD 4422 13.6.11 Subscription / Notification Behavior 4423 Subscription/Notification is RECOMMENDED for this resource to provide automatic synchronization of 4424 billing and consumption data and notification of new target or projection information. If the device 4425 cannot support subscription/notification then it should poll for updates to ensure that the most accurate 4426 information is always available to the end user. 4427 Servers that support subscription/ notification mechanisms SHALL notify interested clients when 4428 resources are created, modified, deleted, or become active. 4429 13.6.12 Application Guidelines / Behavior 4430 13.6.12.1 CustomerAccount Resource 4431 A customer account is related to one usage point. If there are multiple commodities related to the 4432 premises there would be different UsagePoints relating to the commodities and each would have a single 4433 customer account referenced to it. 4434 13.6.12.2 BillingPeriod Resource 4435 Within a customer account there may be multiple billing periods relating to different tariff structures. 154

November, 2011 Draft ZigBee-11167

4436 13.6.12.3 Charge Resource 4437 The Charge resource is meant to provide the ability to describe a customer bill. This could be any form of 4438 charge related to the customer account be it commodity or surcharges. The difference between a charge 4439 and other types of readings is that the information is verified as billing quality information and 4440 representative of what would be billed to the customer. 4441 13.6.12.4 TargetReading Resource 4442 As a good practice, there should be only one TargetReading for a time period. The values of the target 4443 readings will be an absolute measurement similar to a projected reading. If the service provider specifies 4444 the targets in a percentage reduction or other method it MUST be converted to an absolute value. 4445 An example would be a customer who used 100kWh in a previous month with a reduction target of 10%. 4446 This target would be specified in the TargetReading as 90kWh and it would be left to the device to 4447 calculate the percentage or kWh reduction this equates to. 4448 13.6.12.5 ProjectedReading Resource 4449 Projected Readings are tools for service providers to help a customer understand what their consumption 4450 or cost might be projected into the future if all things within the home stayed fairly similar. 4451 Examples of projected readings are:

4452  Consumption for the billing period

4453  Cost of commodity for the billing period

4454  On day X the consumption would be Y which would indicate a customer moving into a higher 4455 block tariff and thus a higher rate

4456  The different TOU tiers at the end of the billing period based on current consumption habits

4457 These are just examples. Other projected readings could be created. 4458 13.6.12.6 HistoricalReading Resource 4459 Historical Readings are meant to provide a resource so that a service provider can provide consumption or 4460 cost that has occurred in the past and could be validated and corrected if REQUIRED. Examples of this 4461 would be:

4462  Previous day

4463  Previous month

4464  Previous billing period

4465  Previous year

4466  TOU A, TOU B, etc

4467  Block 1, Block 2, etc

155

November, 2011 Draft ZigBee-11167

4468  Cost of consumption for TOU A for the billing period

4469 This is just a sample of what could be used. Because the information will be provided from the backend 4470 platform it can be of billing quality or near billing quality. An end device could use this information to 4471 synchronize its consumption or cost estimates between Billing server updates via the Metering and 4472 Pricing Function Set.

156

November, 2011 Draft ZigBee-11167

4473 13.7 Prepayment Function Set 4474 13.7.1 Overview 4475 The prepayment function set defines a mechanism for the conditional delivery of services based upon 4476 outstanding credit or debt. It provides an interface for appropriately privileged clients to view, update or 4477 act upon account balance information. Accounting in prepayment systems may be measured on a 4478 monetary basis (e.g., Dollars or Euros remaining) or on a commodity basis (e.g., kilowatt-hours or BTUs 4479 remaining). A service-providing device (typically a meter) MAY use the account balance information 4480 from a prepayment server in combination with consumption and price data to determine if service should 4481 continue. In some scenarios (“Local” mode), the service-providing device and the prepayment server are 4482 the same. Alternatively, the continuation of service may be directed by an external prepayment server, 4483 either in response to local calculation (“ESI” mode) or to an out-of-band signal from the service provider 4484 (“Central Wallet” mode). Client devices that provide a user interface to the service provider’s customers 4485 may use the prepayment function set to display information about remaining balances or to request 4486 additional credit (in some scenarios, through the transmission of payment tokens). 4487 13.7.2 Dependencies 4488 For the Central Wallet prepayment mode, the Prepayment function set does not require any other function 4489 set. Local and ESI modes, however, at a minimum require the Metering function set. If account balance 4490 information is in a monetary basis, then these modes also require the Base and Pricing function sets (note 4491 that if the Price tariff data does not include all charges, such as taxes and fees, then these charges MUST 4492 be externally signalled. See the Credit Register description below). Although NOT REQUIRED, it is 4493 expected that most Prepayment servers will use the Response function set. 4494 13.7.3 Sequence Diagrams 4495 TBD 4496 13.7.4 URI Structure and Actions 4497 13.7.5 URI Structure 4498 Table 13-15: URI Structure Table for the Prepayment Resource. URI – Assume all URIs Purpose GET PUT POS DELE begin with “http(s)://{ip T TE address}” /ppy A List of Prepayment instances. M O O O /ppy/{#} A particular Prepayment instance. M O O O Provides links to the Account Balance, Credit Register, and Operation Status resources for a particular service. /ppy/{#}/ab Account Balance instance. M O O O /ppy/{#}/cr A List of Credit Register instances. M O M O Interface for new credit transactions. /ppy/{#}/cr/{#} A particular Credit Register instance. M O O O Records a payment transaction or other 157

November, 2011 Draft ZigBee-11167

credit addition. /ppy/{#}/os The Operation Status for the given M O O O service. Identifies whether service should be continued. MAY also include other status information, such as low credit warning. /ppy/{#}/si A List of Supply Interruption Override M O O O instances. /ppy/{#}/si/{#} A particular Supply Interruption Override M O O O instance. This defines a period of time during which supply would not be interrupted even if available credit has been exhausted.

4499 13.7.6 URI Actions 4500 In order to obtain a particular Prepayment instance. 4501 Tthe client would send: 4502 GET /ppy/1 HTTP/1.1 4503 Host: {host} 4504 4505 The server would respond: 4506 HTTP/1.1 200 OK 4507 Content-Type: application/xml 4508 4509 4510 4511 4513 4514 4515 4516 4517 4518 3 4519 72 4520 500 4521 4522 840 4523 -3 4524 250000 4525 4526 4527 4528 4529 3 4530 72 4531 50 4532 4533 840 4534 -3 4535 25000 4536 4537 4538 158

November, 2011 Draft ZigBee-11167

4539 -3 4540 72 4541 50 4542 4543 840 4544 -3 4545 25000 4546 4547 0 4548 4549 4550 4551 In order to obtain a list of CreditRegister instances. 4552 The client would send: 4553 GET /ppy/1/cr HTTP/1.1 4554 Host: {host} 4555 4556 The server would respond: 4557 HTTP/1.1 200 OK 4558 Content-Type: application/xml 4559 4560 4561 4562 4565 4566 4567 4568 3 4569 72 4570 250 4571 4572 840 4573 -3 4574 250000 4575 4576 0 4577 1325376000 4578 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 4579 4580 4581 In order to obtain a specific instance of Account Balance 4582 The client would send: 4583 GET /ppy/1/ab HTTP/1.1 4584 Host: {host} 4585 4586 The server would respond: 4587 HTTP/1.1 200 OK 4588 Content-Type: application/xml 4589 4590 4591 4593 4594 4595 3 4596 72 4597 500 159

November, 2011 Draft ZigBee-11167

4598 4599 840 4600 -3 4601 250000 4602 4603 0 4604 0 4605 4606 In order to obtain Operation Status. 4607 The client would send: 4608 GET /ppy/1/os HTTP/1.1 4609 Host: {host} 4610 4611 The server would respond: 4612 HTTP/1.1 200 OK 4613 Content-Type: application/xml 4614 4615 4616 4617 4620 4621 1 4622 1328054400 4623 4624 0 4625 4626 2 4627 1328054400 4628 4629 0 4630 4631 In order to obtain a list of Supply Interruption Over-ride instances. 4632 The client would send: 4633 GET /ppy/1/os HTTP/1.1 4634 Host: {host} 4635 4636 The server would respond: 4637 HTTP/1.1 200 OK 4638 Content-Type: application/xml 4639 4640 4641 4644 4645 4646 86400 4647 1325376000 4648 4649 4650 4651 13.7.7 Subscription / Notification Behavior 4652 It is RECOMMENDED that Prepayment function set servers support subscriptions for the following 4653 resources:

160

November, 2011 Draft ZigBee-11167

4654 - /ppy

4655 Allows a Prepayment server to advertise its management of account balance data for new services 4656 or commodity types. 4657 - /ppy/{#}

4658 Allows a Prepayment instance to advertise the present prepayment mode and other general 4659 attributes of the system. 4660 - /ppy/{#}/cr

4661 Allows a Prepayment server to advertise the receipt of a new credit transaction for a particular 4662 service instance. 4663 - /ppy/{#}/os

4664 Allows a Prepayment server to advertise changes to the operating status (service connected or 4665 disconnected, credit low, etc.) for a particular service instance. 4666 It is RECOMMENDED that Prepayment function set servers NOT support subscriptions for the 4667 following resources: 4668 - /ppy/{#}/ab

4669 The account balance resource for a particular service instance may be continuously updated based 4670 on commodity or service consumption. Offering subscriptions to this resource is discouraged 4671 because notifications could lead to excess network traffic. 4672 Client devices polling this element are RECOMMENDED to poll no more often than once per 4673 hour, and no less than once per day. Devices are also RECOMMENDED to poll more frequently 4674 (e.g., once every 10 - 30 minutes) if the available credit is less than the low credit warning level 4675 (see Application Guidelines below). However, implementers are free to choose any polling period 4676 so long as it does not disrupt network functionality. 4677 13.7.8 Application Guidelines / Behavior 4678 4679 13.7.8.1 Prepayment 4680 A List of Prepayment instances is the first resource in the Prepayment hierarchy. Each linked-to 4681 Prepayment instance organizes the account balance, credit transaction list, and operational status of each 4682 prepay-enabled service managed by the server. 4683 Servers implementing the Prepayment function set SHALL be capable of internally storing and 4684 supporting at least one Prepayment instance. 4685 13.7.8.1.1 Credit Expiry Level 4686 The set point for availableCredit at which the service level may be changed. The typical value for this 4687 attribute is 0, regardless of whether the account balance is measured in a monetary or commodity basis. 4688 The units for this attribute SHALL match the units used for availableCredit.

161

November, 2011 Draft ZigBee-11167

4689 13.7.8.1.2 Low Credit Warning Level 4690 The set point for availableCredit at which the creditStatus attribute in the AccountBalance resource 4691 SHALL indicate that available credit is low. The units for this attribute SHALL match the units used for 4692 availableCredit. Typically, this value is set by the service provider. 4693 13.7.8.1.3 Low Emergency Credit Warning Level 4694 The set point for emergencyCredit at which the creditStatus attribute in the AccountBalance resource 4695 SHALL indicate that emergencycredit is low. The units for this attribute SHALL match the units used for 4696 availableCredit. Typically, this value is set by the service provider. 4697 13.7.8.1.4 Prepay Mode 4698 Specifies whether the given Prepayment instance is operating in Credit, Central Wallet, ESI, or Local 4699 prepayment mode. The Credit mode indicates that prepayment is not presently in effect. The other modes 4700 are described in the Overview Section above. 4701 13.7.8.2 Account Balance 4702 AccountBalance contains the regular credit and emergency credit balance for this given service or 4703 commodity prepay instance. It may also contain status information concerning the balance data. 4704 Prepay servers SHALL support one and only one AccountBalance resource. 4705 13.7.8.2.1 Available Credit 4706 The balance of the sum of credits minus the sum of charges. In a Central Wallet mode this value may be 4707 passed down to the Prepayment server via an out-of-band mechanism. In Local or ESI modes, this value 4708 may be calculated based upon summation of CreditRegister transactions minus consumption charges 4709 calculated using Metering (and possibly Pricing) function set data. This value may be negative; for 4710 instance, if disconnection is prevented due to a Supply Interruption Override. 4711 13.7.8.2.2 emergencyCredit 4712 The amount of emergency credit still available for the given service or commodity prepayment instance. 4713 If both availableCredit and emergyCredit are exhausted, the prepayment instance typically will 4714 disconnect service. 4715 13.7.8.2.3 Credit Status 4716 Identifies whether the present value of availableCredit is considered OK, low, exhausted, or negative. 4717 13.7.8.2.4 emergencyCredit Status 4718 Identifies whether the present value of emergencyCredit is considered OK, low, exhausted, or negative. 4719 13.7.8.3 Credit Register 4720 Each Prepayment instance includes a link to a List of CreditRegister instances. Each CreditRegister 4721 instance defines a credit-modifying transaction. Typically this would be a credit-adding transaction, but 4722 may be a subtracting transaction (perhaps in response to an out-of-band debt signal). 4723 Servers implementing the Prepayment function set in Local or ESI mode SHALL be capable of internally 4724 storing and supporting at least one CreditRegister instance per Prepayment instance. 4725 Prepayment clients may POST to the List of CreditRegister to transmit a new CreditRegister transaction.

162

November, 2011 Draft ZigBee-11167

4726 13.7.8.3.1 Credit Amount 4727 The amount of credit being added by a particular CreditRegister transaction. Negative values indicate that 4728 credit is being subtracted. 4729 13.7.8.3.2 Credit Type 4730 Whether the credit transaction applies to regular or emergency credit. 4731 13.7.8.3.3 Effective Time 4732 Identifies the time at which the credit transaction goes into effect. For credit addition transactions this is 4733 typically the moment at which the transaction takes place. For credit subtraction transactions (e.g., non- 4734 fuel debt recovery transactions initiated from a back-haul or ESI) this may be a future time at which credit 4735 is deducted.

4736 13.7.8.3.3.1 Token 4737 The secure token data that authenticates the legitimacy of the transaction. The details of this token are not 4738 defined by Smart Energy 2.0. How a Prepayment server handles this field is left as vendor specific 4739 implementation or will be defined by one or more other standards. 4740 13.7.8.3.4 Description 4741 Code or textual description of how/why a particular CreditRegister transaction was generated. For 4742 instance, a debt recovery transaction posted by the service provider MAY include descriptive information 4743 such as "Taxes ($dd.cc) and fees ($dd.cc) for billing period ending dd-mm-yyyy". If not included in the 4744 original POST to the CreditRegister List, this value may be populated by the prepayment server (e.g., it 4745 MAY annotate the entry as "Credit added by customer on dd-mm-yyyy at hh:mm:ss"). 4746 13.7.8.4 Prepay Operation Status 4747 PrepayOperationStatus describes the status of the service or commodity being conditionally controlled by 4748 the Prepayment function set. 4749 A server implementing the Prepayment function set SHALL support one and only one 4750 PrepayOperationStatus resource per Prepayment instance. 4751 A Prepayment client may POST to PrepayOperationStatus to switch between using regular credit and 4752 emergency credit. Typically, this interface is used by service customers to tap a backup credit pool when 4753 normal credit is exhausted and cannot be immediately recharged. Prepayment server implementers MAY 4754 apply additional vendor-specific rules around when this mode of operation may be changed (e.g., 4755 emergency credit might only be allowed when availableCredit is less than or equal to the 4756 creditExpiryLevel).

4757 13.7.8.4.1.1 Service Status 4758 Identifies whether the service is connected or disconnected, or armed for connection or disconnection.

4759 13.7.8.4.1.2 CreditTypeInUse 4760 Identifies whether the present mode of operation is consuming regular credit or emergency credit.

4761 13.7.8.4.1.3 Service Change 4762 Used to define a pending change of serviceStatus, which will activate at a specified time. 163

November, 2011 Draft ZigBee-11167

4763 13.7.8.4.1.4 creditType Change 4764 Used to define a pending change of creditTypeInUse, which will activate at a specified time.

4765 13.7.8.4.1.5 Response Required 4766 Identifies whether the Prepayment clients are expecting the server to send acknowledgements in response 4767 to changes in the server’s serviceStatus and/or creditTypeInUse elements. Typically this is used in Central 4768 Wallet or ESI prepayment modes to flag that external meters should acknowledge changes in the 4769 operation state (and also indicate these external meters have acted upon the change). Further details are 4770 described in the Client/Server Prepayment Interaction Section below. 4771 13.7.8.5 Supply Interruption Override 4772 There may be periods of time when social, regulatory or other concerns mean that service should not be 4773 interrupted, even when available credit has been exhausted. Each Prepayment instance links to a List of 4774 SupplyInterruptionOverride instances. Each SupplyInterruptionOverride defines a contiguous period of 4775 time during which supply SHALL NOT be interrupted.

4776 13.7.8.5.1.1 interval 4777 The period of time during which supply should not be interrupted.

4778 13.7.8.5.1.2 Description 4779 A textual description of why the particular SupplyInterruptionOverride period was granted (e.g., 4780 "Weekend grace period" or "National holiday"). 4781 13.7.8.6 Mirroring Behavior 4782 In most Smart Energy 2.0 function sets, mirroring involves behavior similar to the following behavior: 4783 1. Server A configures a mirror instance for Server B.

4784 2. Server B posts its data to the mirror instance on Server A.

4785 3. Client C reads Server B data from the mirror instance on Server A.

4786 The Prepayment function set, in some deployments, requires additional mirroring behavior. With 4787 Prepayment, mirror instances MAY need to act as mailboxes for the mirrored server, such as in the 4788 following scenario: 4789 1. Server A configures a mirror instance for Server B.

4790 2. Client C POSTS data to the mirror instance on Server A.

4791 3. Server B reads the mirror instance on Server A to see what Client C had to say.

4792 One use case for this mode is when a sleepy meter is implementing a Prepayment server in local 4793 prepayment mode. This means that the meter will be expecting CreditRegister transactions to be posted 4794 by prepayment clients. However, sleepy devices are unable to receive transmissions while idle, and a 4795 sleepy server will typically be interacting with other HAN devices through a mirrored instance. In this 4796 scenario, prepayment clients SHALL post the CreditRegister transactions to the mirrored instance. The 164

November, 2011 Draft ZigBee-11167

4797 server hosting the mirrored instance SHALL maintain the List and instances of CreditRegister 4798 transactions, so that the sleepy meter MAY download and act upon the credit transactions. 4799 13.7.8.7 Application Guidelines 4800 In most Prepayment configurations, client behavior is minimally affected by server state. That is, the 4801 typical client is an IHD that displays the present account and status data, posts new credit transactions, 4802 requests the use of emergency credit, or displays historical transaction data. However, in the ESI 4803 prepayment mode (and in some configurations of the Central Wallet mode), external meters (or other 4804 service-providing devices) are also prepayment clients. These clients are significantly affected by server 4805 state. These devices SHALL monitor the server’s Operation Status resource and should react 4806 appropriately to changes of the serviceStatus and serviceChange elements. This reaction includes 4807 connecting or disconnect service, and (if specified by the PrepayOperationStatus responseRequired 4808 attribute) sending acknowledgements of operational changes. 4809 Note that in some cases the meter’s acknowledged change MAY not exactly match the server’s status. For 4810 instance, if an ESI Prepayment server changes its serviceStatus from Connected to Disconnected, a 4811 prepayment client meter MAY only be able to enter the Armed for Disconnect state due to physical 4812 constraints of the deployment. In such a case, the meter’s acknowledgement SHALL POST a 4813 PrepayResponse with the serviceStatusApplied attribute set to Armed for Disconnect. If the client meter 4814 does not contain a disconnect mechanism, it SHALL POST a PrepayResponse with the 4815 serviceStatusApplied attribute set to No Contactor. If other special cases arise, the meter SHALL POST a 4816 PrepayResponse with the serviceStatusApplied attribute set to Other; the description attribute (provided 4817 by the base IdentifiedObject class) may be used to indicate special condition codes, but these codes are 4818 not specified by the Smart Energy profile.

4819 13.8 DER Control: (formerly: Distributed Energy Resources Function Set) 4820 13.8.1 Overview 4821 In specific cases, energy MAY be provided to and managed by the grid. In these cases, energy load, area 4822 capabilities, costs and transfer of energy timing impact the management of accepting power. 4823 Management of the necessary energy is achieved according to the scheduling of energy via requested and 4824 accepted energy transfer transactions. 4825 This function set provides an interface to control Distributed Energy Resources. Client devices of this 4826 function set include solar inverters, fuel cells, generation units and battery storage systems. Server 4827 devices of this function set include ESIs and premises energy management systems. 4828 Servers expose load control events called “DERControls” (DERC), to client devices. All DERC instances 4829 will expose attributes that allow devices to respond to events that are explicitly targeted at their device 4830 type. For example, a DERC MAY contain an Offset object indicating a watt offset to be applied to a 4831 DER output. The DERC will also expose necessary attributes that DER devices will need in order to 4832 process an event. These include Start Time and Duration, as well an indication on the need for 4833 randomization at the start or end of the event. 4834 These resources are detailed out in the following Sections.

4835  Distributed Energy Resources Program /derp

4836  Distributed Energy Resources Control /derc

165

November, 2011 Draft ZigBee-11167

4837  Distributed Energy Resources /der 4838  Charging/Discharging Reservation /crsv 4839 For additional information regarding Plug-In Electrical Vehicle (an example of a Distributed Energy 4840 Resource, with reservations, control and program membership), please review the “PEV Appendix”. 4841 13.8.2 Dependencies 4842 Distributed Energy Resources (DER) are Devices which utilize a Reservation for transfer of energy, when 4843 load, cost and timing is such that a simple energy transfer does not suffice. Reservations for DER 4844 require that the following resource be present in the HAN:

4845  Base Function Set (e.g., time, …)

4846  Metering Function Set

4847  Demand Response Load Control Function Set (DRLC)

4848  Pricing Function Set

4849  Enrollment Function Set

4850  End Device Group Function Set

4851 13.8.2.1.1 URI Structure and Actions

4852 13.8.2.1.1.1 URI Structure 4853 Table 13-16: URI Structure Table for the DER Resource. URI - Purpose GET PUT POST DELE http{s}://{host} TE /derp List of DERProgram instances. Devices M O O O implementing the /derp resource MAY

support multiple instances of DERPrograms. /derp/{#} Specific DER Control Program M O O O collection resource. This resource can

be thought of as a particular DERProgram endpoint. This representation contains simple management attributes, as well as each associated resource. /derp/{#}/csrv List of ChargeReservations. Devices M O O O implementing the /derp/{#}/csrv

resource MAY support multiple ChargeReservations.

166

November, 2011 Draft ZigBee-11167

/derp/{#}/csrv/{#} Specific ChargeReservation resource. M O O O This resource can be thought of as a

particular reservation event for fast charging over a period of time. /derp/actcsrv List of ChargeReservations that are M O O O currently active.

/derp/{#}/derc List of DERControls. Devices M O O O implementing the /derp/{#}/derc

resource MAY support multiple DERControls.

/derp/{#}/derc/{#} Specific DERControl resource. This M O O O resource can be thought of as a

particular DER control event for a period of time. /derp/actderc List of DERControls that are currently M O O O active.

4854

4855 13.8.2.1.1.2 URI Actions 4856 To obtain a particular DERProgram instance. 4857 The client would send: 4858 GET /derp/1 HTTP/1.1 4859 Host: {host} 4860 The server would respond: 4861 HTTP/1.1 200 OK 4862 Content-Type: application/xml 4863 4864 4865 4868 91f27e469127 4869 4870 4871 4872 4873 1 4874 4875 167

November, 2011 Draft ZigBee-11167

4876 To obtain status of a particular DER instance. 4877 The client would send: 4878 4879 GET /der/1/ders/HTTP/1.1 4880 Host: {host} 4881 The server would respond: 4882 HTTP/1.1 200 OK 4883 Content-Type: application/xml 4884 4885 4886 4889 86400 4890 100 4891 1 4892 1325376000 4893 1 4894 false 4895 false 4896 4897 To obtain information about a particular DER instance. 4898 The client would send: 4899 GET /der/1 HTTP/1.1 4900 Host: {host} 4901 The server would respond: 4902 HTTP/1.1 200 OK 4903 Content-Type: application/xml 4904 4905 4906 4908 4909 -3 4910 106 4911 500 4912 4913 4914 4915 0 4916 29 4917 220 4918 4919 4920 3 4921 38 4922 300 4923 4924 1 4925 4926 To obtain a particular instance of DERControl event. 4927 The client would send: 4928 GET /derp/1/derc/1 HTTP/1.1 4929 Host: {host} 4930 The server would respond: 4931 HTTP/1.1 200 OK 4932 Content-Type: application/xml 4933 168

November, 2011 Draft ZigBee-11167

4934 4935 4938 e8626b267a10 4939 4940 3 4941 38 4942 300 4943 4944 4945 28800 4946 1328054400 4947 -60 4948 60 4949 4950 4951 1325376000 4952 0 4953 4954 4955 0 4956 65 4957 0 4958 4959 false 4960 4961 This should be POSTed by the client to the ESI. 4962 4963 4964 4967 b637d729e9a98740 4968 4969 4970 28800 4971 1325376000 4972 4973 4974 4975 13.8.2.2 Subscription / Notification Behavior 4976 Subscription/Notification is RECOMMENDED for resources to provide synchronization of DER data and 4977 notification of scheduling or charging information. If the DER client cannot support 4978 subscription/notification then it should poll for updates to ensure that the most accurate information is 4979 always available to the end user. 4980 Servers that support subscription/ notification mechanisms SHALL notify interested clients when 4981 resources are created, modified, deleted, or become active. 4982 DER function set servers should provide the ability for DER clients to subscribe to the following 4983 resources: 4984 - The collection of DERControlProgram instances

4985 - The collection of DERControls within one DERControlProgram

4986 - A collection of active DERControl instances 169

November, 2011 Draft ZigBee-11167

4987 - A specific DERControl instance

4988 Client devices can subscribe to the DERProgram collection to be notified of any changes to the list. 4989 Servers SHALL notify subscribed clients at the moment that the change occurs on the list. 4990 Client devices can subscribe to a collection of Transfer of Energy Reservation instances to receive 4991 updates when a new event is added. 4992 Client devices can subscribe to a collection of DERControls under one DERControlProgram instance. 4993 DER Control Servers are responsible for notifying subscribers when a change occurs on the list. 4994 Client devices can subscribe to a collection of active DERControl instances to receive updates when a 4995 new event is added into the active list. Servers are responsible for notifying clients of any events that 4996 have become active at the earliest effective start time of the event. For example, if an event is scheduled 4997 to begin at 2:00 PM and includes a negative start time randomization of 10 minutes, the events SHALL be 4998 considered active from 1:50 PM until its effective end time. 4999 Client devices can subscribe to a specific DERControl to stay up to date on any changes to the event. 5000 When the client device discovers a new instance of a DERControl, it can subscribe to that instance to 5001 allow it to be notified of any changes. Servers are responsible for notifying their subscribers at the 5002 moment a change to the DERControl instance occurs. The Status object will be used to report on the type 5003 of change that has occurred. 5004 13.8.3 Application Guidelines / Behavior

class DER Control

IdentifiedObject EndDev iceGroup

0..1

Link DERProgramListLink

IdentifiedObject DERProgram Link Activ eDERControlListLink + primacy: PrimacyType 0..1 Link 0..1 DERControlListLink

IdentifiedObject DERControl ActivePower + gnBlk: boolean [0..1] Status + multiplier: PowerOfTenMultiplierType [0..1] + gnCtl: boolean [0..1] + unit: UomType [0..1] = 38 {readOnly} + dateTime: TimeType + gnRL: boolean [0..1] 0..1 + value: UInt16 [0..1] + scheduledInterval: RandomizedDateTimeInterval + reason: String192 [0..1] + maxOperatingPower: ActivePower + type: UInt8 + targetPowerFactor: PowerFactor PowerFactor + varSupportMode: boolean + multiplier: PowerOfTenMultiplierType [0..1] + unit: UomType [0..1] = 65 {readOnly} + value: UInt16 [0..1] 5005 5006 Figure 13.8-1: Application Guidelines / Behavior for the DER Resource. 5007 13.8.3.1 DERProgram 5008 DERProgram is used by service providers to offer DER programs. Multiple programs can be created to 5009 target different types of devices or to offer different types of incentives. DERProgram SHALL have a 5010 unique identifier selected by the service provider, the identifier MUST NOT follow any specific order,

170

November, 2011 Draft ZigBee-11167

5011 but it’s RECOMMENDED that an ascending order be used for simplification. Identifiers SHALL NOT 5012 be reused until all possible values have been used. 5013 13.8.3.2 DERControl 5014 A DERControl is used to provide control parameters to a DER client. DERControl SHALL have a 5015 unique identifier selected by the service provider, the identifier MUST NOT follow any specific order, 5016 but it’s RECOMMENDED that an ascending order be used for simplification. Identifiers SHALL NOT 5017 be reused until all possible values have been used. A DERControl can always be overridden by the user. 5018 DER Control server devices MUST be capable of internally storing and supporting at least 5 unique 5019 DERControl instances. The collection of DERControls SHALL be a time ordered list, where events with 5020 the earliest scheduled start time, including events that have been cancelled, will be first on the list. A 5021 second criterion for ordering SHALL be the primacy flag, where events labeled as primary by the service 5022 provider will take higher precedence in the list. Servers are responsible for maintaining DERControls on 5023 their list, including cancelled events, for the duration of the event plus the maximum start and end 5024 randomization allowable. Servers are also responsible for removing events from their list that have 5025 expired or have been cancelled and their effective end time has passed. If a server receives a new 5026 DERControl and no longer has room in its collection, it MAY remove an existing event to make room for 5027 the new one; however this will not indicate that the event has been canceled. When clients do not see an 5028 event on the server’s list that they previously retrieved, they should continue to operate as if the event still 5029 exists. Servers are responsible for selecting which events to remove to make room for new ones. 5030 DER Control client devices MUST be capable of internally storing and supporting at least 3 unique 5031 DERControl instances. As a highly RECOMMENDED recovery mechanism, when a maximum of 5032 storage of events has been reached and additional DERControl instances are available on the server(s), 5033 clients should ignore additional DERControl instances and, when additional storage becomes available, 5034 query the DER Control server representing the list of available DERControl instances and then 5035 subsequently retrieve any previously ignored DERControl instances. Additionally, clients should 5036 prioritize local storage and give preference to DERControls with start times in the near future and to 5037 events that have been flagged as mandatory. 5038 Devices are also RECOMMENDED to continue to poll even when their event buffer is full. This will 5039 allow them to stay up to date on new events that MAY replace or supersede events already on their list. 5040 This will also keep devices updated with any changes to events they have already stored. 5041 The most recent DERControl supersedes any previous DERControl for a set of HANDeviceAssets and 5042 EndDeviceGroup for a given time. Nested events and overlapping events are not allowed. The current 5043 active event will be terminated if a new event is started. 5044 13.8.3.2.1 HANDeviceAssetCategoryType 5045 HANDeviceAssetCategoryType is used within an DERControl to target a specific type of device. This 5046 attribute will indicate which type of device is being targeted. A DERControl MAY target multiple 5047 HANDeviceAssetCategoryTypes. 5048 13.8.3.2.2 RandomizeDateTimeInterval 5049 The RandomizeDateTimeInterval object will provide randomization parameters as well as start time and 5050 duration for the DERControl. 5051 Randomization provides two signed attributes, randomizeEnd and randomizeStart. None, one, or both of 5052 these may be included as part of an DERControl. 171

November, 2011 Draft ZigBee-11167

5053 13.8.3.2.2.1 randomizeEnd 5054 The randomizeEnd represents the maximum number of seconds to be used when randomizing the end of 5055 an event. As an example, if randomizeEnd is set for 180 seconds, the device SHALL randomly select a 5056 number in seconds from zero to the randomizeEnd specified (e.g., 120 seconds) for this event. Depending 5057 on the sign of the value (positive or negative), randomization SHALL be applied before or after the 5058 scheduled end time of the event. If the value is negative, randomization SHALL be applied before the 5059 specified end time of the event. For example, if an event is scheduled to conclude at 1:00PM and has a 5060 randomizeEnd of -180, a device can select to end the event at 12:59AM, indicating a negative 1 minute 5061 randomization. If the value is positive, randomization SHALL be applied after the specified end time of 5062 the event, causing the device to delay termination of the event. The valid range for this attribute is -3600 5063 to 3600 (e.g., 60 minutes). 5064 Refer to the Randomization Section for additional guidelines.

5065 13.8.3.2.2.2 randomizeStart 5066 The randomizeStart represents the maximum number of seconds to be used when randomizing the start of 5067 an event. As an example, if randomizeStart is set for 180 seconds, the device SHALL randomly select a 5068 number in seconds from zero to the randomizeStart specified (e.g., 120 seconds) and apply it for the 5069 event. Depending on the sign of the randomizeStart (positive or negative), randomization SHALL be 5070 applied before or after the specified start time of the event. If the value is negative, randomization 5071 SHALL be applied before the specified start time of the event. For example, if an event is scheduled to 5072 start at 11:00AM and has a randomizeStart of -300, a device can select to begin the event at 10:58AM, 5073 indicating a negative 2 minute randomization. If the value is positive, randomization SHALL be applied 5074 after the specified start time of the event, causing the device to delay commencement of the event. The 5075 valid range for this attribute is -3600 to 3600 (e.g., 60 minutes). 5076 Refer to the Randomization Section for additional guidelines.

5077 13.8.3.2.2.3 DateTimeInterval 5078 DateTimeInterval provides two attributes, duration and start. 5079 The duration of the DERControl is provided in seconds using the duration attribute. 5080 The start time for a DERControl is provided using the start attribute, which is a signed 64 bit value 5081 representing the number of seconds since 0 hours, 0 minutes, 0 seconds, on the 1st of January, 1970. 5082 13.8.3.2.3 Response Mandatory 5083 Provides the ability for DER service providers to require that clients confirm receipt of a DERControl. 5084 This is thought to be useful in determining non-repudiation. Client devices SHALL use the Response 5085 resource to provide the confirmation. 5086 13.8.3.3 Duty Cycle 5087 Duty cycle is a method of control and defines the maximum ON state of the device as a percentage of a 5088 defined time period, this value is provided through the normalValue attribute. For example, if the value is 5089 80, the device would be in an “on state” for 80% of the time for the duration of the event. Range of the 5090 value is 0 to 100. All other values are reserved for future use. Duty cycle control is a device specific 5091 issue and SHALL be managed by the device manufacturer. The duty cycle of the device under control 5092 should span the shortest practical time period in accordance with the nature of the device under control 172

November, 2011 Draft ZigBee-11167

5093 and the intent of the request for DER Control. The default factory setting SHALL be three minutes for 5094 each 10% of duty cycle3. The service provider MAY modify these settings. The “off state” SHALL 5095 precede the “on state.” 5096 13.8.3.4 Offset 5097 The Offset object is used to apply a change in watts to a specific device. The type attribute will indicate 5098 what type of offset that SHALL be applied. 5099 If a watt offset is applied, the value attribute will be calculated as follows: 5100 Watt offset (Delta Watt) a control event requesting an increase (+) or decrease (-) of Watt output of a 5101 DER device . 5102 If a watt output is sent that causes the DER device to exceed the limit boundaries that are programmed 5103 into the device, the device should respond by setting the watt output at the limit. 5104 If an Adjustment Percentage is applied, the value attribute will be calculated as follows: 5105 A 10% load adjustment percentage will establish an energy usage limit equal to 90% of the client 5106 implementation’s specific average energy usage. Each load adjustment percentage is referenced to the 5107 client implementation’s specific average energy usage. There are no cumulative effects. Range of the 5108 value is 0 to 100. 5109 If a DERC is being targeted at multiple devices or to a device that controls multiple devices (e.g., EMS), 5110 it can provide multiple Offset instances within one DERC. 5111 13.8.3.5 Status 5112 The Status object is used to indicate the current status of a DERControl. Devices can read this object to 5113 get the most up to date status of the event. Device can also subscribe to a specific DERControl instance 5114 to get updates if any attributes change, including the Status object. 5115 Devices that do not subscribe to a DERControl instance SHALL read the instance before executing any 5116 event that has been scheduled in the past. These devices are also RECOMMENDED to read this resource 5117 every 5 minutes while the event is active, this will allow them to be aware of any changes during the 5118 event. 5119 The DER Control Function Set server is REQUIRED to provide a subscription mechanism for any 5120 DERControl instance on its current list. When an event status changes, the server SHALL update the 5121 Status object within the DERControl to indicate the new status, along with the time the new status 5122 became effective. The server SHALL notify all subscribers of a change to a DERControl instance. The 5123 server may also provide the reason for the change using the Reason attribute in the Status object, where it 5124 can provide a textual explanation of the change. 5125 There are 4 specified types of status, they are described below.

5126 - Scheduled

5127 This status indicates that the event has been scheduled and the event has not yet started. The 5128 server SHALL set the event to this status when the event is first scheduled and persist until the

3 See CCB 1173 for SEP 1.x

173

November, 2011 Draft ZigBee-11167

5129 event has begun or has been cancelled. For DERControls with a start time equal to the current 5130 time, this status SHALL never be indicated; the event SHALL start with a status of “Active”. 5131 - Active

5132 This status indicates that the event is currently active. The server SHALL set the event to this 5133 status when the event reaches its earliest possible effective start time and persist until the event 5134 has completed or been cancelled.

5135 - Cancelled

5136 When DERControls are cancelled, the dateTime attribute can be used to indicate the effective 5137 time of the cancellation. If a server would like to cancel the event immediately, it would provide 5138 a dateTime value with the current time. The server is responsible for maintaining the cancelled 5139 event in its collection for the duration of the original event. 5140 - Cancelled with Randomization

5141 DERControls that are cancelled with randomization will use the dateTime attribute to indicate the 5142 effective time. Devices SHALL cancel the event using the original settings for randomization. 5143 The server is responsible for maintaining the cancelled event in its collection for the duration of 5144 the original event plus any randomization. 5145 Editing of a scheduled DER control event is not allowed. Editing of an active DER control event is not 5146 allowed. Nested events and overlapping events are not allowed. The current active event will be 5147 terminated if a new event is started. 5148 13.8.3.6 TargetedOutput 5149 The TargetOutput object is used by a DER Control service provider to provide a RECOMMENDED 5150 threshold that a device/premises should maintain its consumption below. For example, a service provider 5151 can provide a RECOMMENDED threshold of some kWh for a 3-hour event. This would mean that the 5152 device/premises would maintain its consumption below the specified limit for the specified period. When 5153 the device/premises receives the event it will POST a Response to the ESI with a Status of “Event 5154 Received”. When the start time of the event arrives the device/premises will POST a Response to the ESI 5155 with a Status of “Event Started”. When the event completes the device/premises will POST a Response to 5156 the ESI with a Status of “Event Completed”. 5157 The service provider SHALL use the Type attribute to indicate the type of unit being used to indicate the 5158 threshold and the Value attribute to indicate the desired threshold. A DERControl MAY contain multiple 5159 TargetOutput instances. 5160 13.8.3.7 VARSupportMode 5161 The VARSupportMode object is used by a DER Control service provider to place DER equipment in a 5162 mode to output AC power with a desired phase angle . When the device/premises receives the event it 5163 will POST a Response to the ESI with a Status of “Event Received”. When the start time of the event 5164 arrives the device/premises will POST a Response to the ESI with a Status of “Event Started”. When the 5165 event completes the device/premises will POST a Response to the ESI with a Status of “Event 5166 Completed”.

174

November, 2011 Draft ZigBee-11167

5167 13.8.3.8 DER Availability 5168 The DERAvailability object is used by client devices to report their current generation status and their 5169 availability to generate power. It can also be used by devices that are able to report this information on 5170 behalf of other devices. This object has three flags, the generating flag reports if the device is currently 5171 outputting any power, the modified output flag is used to indicate if the device is currently operating in a 5172 control mode, and the shed flag is used to indicate if the device is capable of shedding load. The type 5173 attribute SHALL be used to indicate the type of commodity available for reduction along with the value 5174 attribute to indicate the amount. The availability attribute may be provided to indicate how long the 5175 generation can be sustained for. 5176 13.8.3.9 Response 5177 Clients of this function set SHALL use the Response resource to report on their participation in 5178 aDERControl. Clients will POST a Response on the ESI with a Status from the following list for each 5179 action taken on the event. For example, a common sequence would have the device POSTing a Response 5180 of “Event Received” when it first receives the event, “Event Started” when it starts the event and “Event 5181 Completed” when it has completed the event. 5182 Table 13-17: Event Status Table. 0x00 Reserved

0x01 Event Received

0x02 Event Started

0x03 Event Completed

0x04 User has chosen to “Opt-Out”, user will not participate in this event

0x05 User has chosen to “Opt-In”, user will participate in this event

0x06 The event has been cancelled

0x07 The event has been superseded

0x08 Event partially completed with User “Opt-Out”.

0x09 Event partially completed due to User “Opt-In”

0x0A Event completed, no User participation (Previous “Opt-Out”)

0x0B Reserved

0x0C to 0xF7 Reserved

0xF8 Rejected - Invalid Cancel Command (Default)

175

November, 2011 Draft ZigBee-11167

0xF9 Rejected - Invalid Cancel Command (Invalid Effective Time)

0xFA Reserved

0xFB Rejected - Event was received after it had expired (Current Time > Start Time +Duration)

0xFC Reserved

0xFD Rejected - Invalid Cancel Command (Undefined Event)

0xFE Load Control Event command Rejected

0xFF Reserved

5183 5184 Additional guidelines on how the Response resource works are provided in the Response Function Set. 5185 13.8.3.10 Rules and Guidelines

5186 All DERControls SHALL include at least one of the OPTIONAL control parameters: DutyCycle, Offset, 5187 SetPoint, or TargetOutput. If a DERControl includes more than one control parameter the end device 5188 SHALL process the event and select the applicable parameter. If the end device is capable of supporting 5189 multiple parameters from the ones that have been included in the event, it should select the parameter that 5190 will lead to the most energy production.

5191 Refer to the Common Application Functionality for additional rules and guidelines. 5192 13.8.4 PEV ANNEX 5193 For additional information regarding Plug-In Electrical Vehicle (e.g, Distributed Energy Resource, with 5194 reservations, control and program membership), please review Section 16 Appendix. 5195

176

November, 2011 Draft ZigBee-11167

5196 5197 5198

5199

177

November, 2011 Draft ZigBee-xxxxxx

5200 14 Manufacturer – Specific Proprietary Extensions 5201 5202 Overview 5203 This Section describes rules and mechanisms for interested parties to extend the Smart Energy Profile 2.0 5204 with proprietary extensions. 5205 This Section addresses the following aspects: 5206 - mDNS/DNS-SD 5207 - URIs 5208 - Resources 5209 It should be noted that as the Smart Energy Profile 2.0 is intended to run over an IP stack, many 5210 techniques already exist for providing proprietary services over such a stack with various protocols. This 5211 Section is intended for guidance to developers of proprietary extensions that may wish to be similar to the 5212 design of the Smart Energy Profile 2.0 or add extended elements to the Smart Energy Profile 2.0. 5213 mDNS/DNS-SD 5214 Proprietary extensions SHALL NOT be made using the “smartenergy” Service Type. 5215 It is RECOMMENDED that proprietary extensions that wish to use mDNS/DNS-SD apply for a new 5216 Service Type with which to operate.

5217 URIs 5218 As URIs are dynamically discovered and used, proprietary extensions are free to place proprietary 5219 resources at URIs of their choosing. It is RECOMMENDED that proprietary resources not be placed at 5220 URIs ‘RECOMMENDED’ in this specification. 5221 Resources 5222 Proprietary extensions SHALL NOT place any objects, elements, attributes, etc. in the standardized SEP 5223 XML namespace (“http://zigbee.org/sep”) and instead SHALL be placed in a different XML namespace. 5224 The following examples demonstrate allowed and disallowed extensions. In these examples, 5225 “SEPElement{#}” is used to demonstrate elements that are defined in the SEP schema. 5226 “MFEElement{#}” and “MFENS” are used to demonstrate elements and namespaces that are proprietary 5227 extensions respectively. 5228 The example given in Figure 13.8-1 demonstrates allowed and disallowed (crossed out) element 5229 extensions.

Smart Energy Profile 2.0 Page 178 Draft Application Protocol Specification November, 2011 Draft ZigBee-xxxxxx

Allowed Disallowed xmlns:MFENS="http://foo.org/mfe"> a a b b c c 5230 5231 5232 Figure 13.8-1: Allowed and dissallowed extensions 5233 Proprietary extensions SHALL NOT extend standard enumerations defined in the SEP schema. 5234 Proprietary extensions made to standardized objects (in a proprietary namespace) SHALL be able to be 5235 ignored. That is, should a device that does not understand the proprietary extension ignore the extension, 5236 behavior will continue per this specification. 5237 Proprietary extensions made to standardized objects (in a proprietary namespace) SHALL NOT change 5238 the semantics of standard elements. 5239 DeviceCapabilities Resource 5240 It is RECOMMENDED that proprietary extensions use a different resource in which to list further 5241 resources. 5242 Should a proprietary extension wish to use the standard DeviceCapabilities resource, it MUST do so 5243 following the same rules as for other resource.

5244

5245 SE 2.0 Development Plan (Wuxi Agreement) 5246 During the June 2011 ZigBee Members meeting in Wuxi,China, the following text in Annex iii was 5247 agreed by unanimous vote. 5248 5249 SE 1.x Devices 5250 • SE 1.x devices that can be upgraded to SE 2.0 may do so. 5251 • SE 1.x devices that cannot be upgraded to SE 2.0, (due to memory or logistical constraints for 5252 example) would require an Application Gateway (ALG) to proxy data between 1.x and 2.0 5253 networks. 5254 • The SE workgroup will document a mapping (as best as possible) 1.x and 2.0 function sets 5255 for use by ALG implementers. 5256

5257 Extreme Long Life Battery 5258 Operated Sensors 5259 • CoAP/UDP is an acceptable application and transport protocol for sensors (such as gas and 5260 water meters) to POST their data to a meter.

Smart Energy Profile 2.0 Page 179 Draft Application Protocol Specification November, 2011 Draft ZigBee-xxxxxx

5261 • Device will post data to HTTP-CoAP proxy (typically electric meter). 5262

5263 CoAP vs. HTTP for other devices 5264 • All devices that have server function sets would be required to support HTTP. This is so they can 5265 service standards based HTTP clients. All devices that have server SE function sets would be 5266 required to support HTTP on their server side. 5267 • CSG workgroup will proceed with testing CoAP and present findings. 5268 • Members will analyze results. Advocates will get a chance to present their views and advocate for 5269 their position. 5270 • SE Workgroup would have a technical vote to decide if CoAP can be optionally used between 5271 client devices and ESI devices. (These client devices would typically be battery operated clients 5272 but could also be line powered clients that wanted to use CoAP for perceived performance 5273 reasons.) 5274 • If it were decided (via workgroup vote) that CoAP was acceptable to use for client functionality, 5275 then it would be mandatory for ESI server devices to support it. Decision will go into 0.9 app 5276 spec candidate. 5277 • If it were decided (via workgroup vote) that CoAP was acceptable to use for client functionality, 5278 the version of CoAP used in the SE2.0 1.0 release will be specified, and may not have reached 5279 full IETF approval. It is expected that when CoAP does reach full IETF approval, the SE group 5280 would adopt it into a later revision of SE 2.0. 5281 5282 App Data Compression 5283 • A group will be formed to examine and test various application data compression schemes such 5284 as EXI, Deflate, Fast Infoset, etc. Group will present findings and members will analyze results. 5285 • Advocates will get a chance to present their views and advocate for their position. 5286 • Workgroup will have a technical vote to pick an application data compression method. 5287 • If the application data scheme is picked before the 0.7 candidate goes to re-ballot, the decision 5288 will be documented in the 0.7 candidate specification. If not, the data compression scheme 5289 selected will go into the 0.9 spec candidate. 5290

5291

5292

Smart Energy Profile 2.0 Page 180 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

5293 15 Compression Mechanism

5294 15.1 Options for Compression of HTTP Data at the SE2.0 Application layer 5295 In keeping with the efficiency requirements for SE2.0, it is of interest to explore options for the 5296 compression of HTTP data that are exchanged between clients and servers in a SE2.0 network. The 5297 choice of a suitable compression technique should be influenced by implementation complexity, storage 5298 requirements and impact on network bandwidth efficiencies. With these in mind, it should be noted that 5299 the use of plaintext HTTP headers and plain XML might indeed be suitable for smaller application 5300 payloads, avoiding the implementation complexity of compression/decompression techniques. If the large 5301 fraction of application payloads are not verbose, then this may indeed be a valid design choice. 5302 Listed below are a set of compression options that SHALL be evaluated based on the tradeoff between 5303 computation/implementation complexity and bandwidth efficiency. 5304 Use of TLSCompressed records. TLS allows negotiation of a compression method to compress and 5305 decompress TLS records. RFC 5246 does not prescribe any method but points to RFC 3749, which 5306 describes using the DEFLATE algorithm (in turn defined in RFC 1951). 5307 Use of standard compression/decompression algorithms: This list includes DEFLATE (LZ77 and 5308 Huffman), compress (LZW) and bzip2 (RLE, BWT and Huffman). Use of pre-placed dictionary in 5309 conjunction with these compression methods SHALL be evaluated 5310 Use of EXI encoding of XML payloads: This technique SHALL be evaluated based on extensibility, 5311 ability to include manufacturer specific options among other factors. A complete description of the use of 5312 various operational modes provided by the EXI standard SHALL be proposed and discussed to establish 5313 feasibility. 5314 Consideration will also be given to storage requirements, e.g., dictionary size, persistence, possibility of 5315 storage in flash or RAM, memory requirements, the commonality of the dictionary to all client/server 5316 relationships. 5317 In practice, we expect that the use of techniques like DEFLATE, compress and bzip2 provide a middle 5318 ground between using plain XML and the implementation complexity of and extensible, future-proof EXI 5319 solution. 5320 The SE2.0 Editors and Proof-Of-Concept participants SHALL undertake this application payload 5321 optimization effort with the objective of reaching a suitable conclusion before the balloted version of the 5322 Application Specification is re-circulated. 5323

Smart Energy Profile 2.0 Page 181 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

5324 16 Appendices [INFORMATIVE]

5325 16.1 Transaction Sequence Examples 5326

5327 16.2 Pricing Implementation Guidelines 5328

5329 16.3 PEV Implementation Guidelines (subject to work with SAE and ISO/IEC) 5330 16.3.1 PEV – Plug-in Electric Vehicle 5331 16.3.1.1 Overview 5332 This PEV appendix document is intended as informational documentation of PEV data and details 5333 identified to provide data and control information to/from the PEV/Grid. The goal is to provide 5334 informative details back to the SEP 2.0 community of the meaningful data utilized with regard to PEV’s. 5335 As such, energy would be provided and managed via the smart grid. In these cases; Energy Load, Area 5336 Capabilities, Costs and Transfer of Energy Timing impact the management of providing power and 5337 information. 5338 PlugIn Electric Vehicles (PEV) are identified Devices which utilize a Reservation for Transferring of 5339 energy, when Load, Cost and Timing is such that, a simple energy transfer does not suffice. The unique 5340 capability of a PEV to be mobile creates additional operational challenges in the smart grid. 5341 Reservations for PEV require the following server resources be present in the HAN:

5342  Base function Set (e.g., Time…)

5343  Pricing Function Set

5344  Enrollment

5345  Demand Response Load Control

5346  Time Tariff Interval

5347  End Device Group

5348  Operational Scenarios

5349  Registration / Joining the HAN 5350

5351 16.4 Fixed Schemas 5352 The object model yields a collection of XML Schema Definitions (XSDs). The XSDs are written in XML 5353 and employ versioned data types and namespaces tied to the object model. The XSDs are provided in a 5354 separate package available for download [ZB 105629]. The following requirements SHALL be met for 5355 the Smart Energy 2.0 Application:

Smart Energy Profile 2.0 Page 182 Draft Application Protocol Specification November, 2011 Draft ZigBee-11167

5356 5357  The schema SHALL be fixed and extended, or portions deprecated but not deleted, for future 5358 releases of the Smart Energy application profile. 5359  Updates to the Smart Energy 2.0 Application Specification shall never redefine existing schemas 5360 such that fielded devices are REQUIRED to communicate with newer devices developed to an 5361 updated schema where data types or name spaces are redefined. 5362 The introduction of fixed schema, with the requirement to extend or deprecate and never redefine permits 5363 definition of low cost, fixed schema based devices. To maintain forward compatibility with these devices, 5364 the Smart Energy 2.0 object model and schema MUST be maintained and managed to support forward 5365 compatibility.

Smart Energy Profile 2.0 Page 183 Draft Application Protocol Specification